allow sp relayState to be overridden in login request

docs/template.md

@@ -19,14 +19,14 @@ then the attributes part will be included in the template string:
 
 ```xml
 <saml:AttributeStatement>
-  <saml:Attribute 
+  <saml:Attribute
     Name="mail"
     NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
     <saml:AttributeValue xsi:type="xs:string">
       {attrUserEmail}
     </saml:AttributeValue>
   </saml:Attribute>
-  <saml:Attribute 
+  <saml:Attribute
     Name="name"
     NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
     <saml:AttributeValue xsi:type="xs:string">
@@ -43,57 +43,57 @@ the tag name is auto-generated with prefix `attr` and the suffix is formatted as
 Developer can design their own request and response template for log-in and log-out respectively. There are optional parameters in setting object.
 
 ```javascript
-const saml = require('samlify');
+const saml = require("samlify");
 
 // load the template every time before each request/response is sent
 const sp = saml.ServiceProvider({
-  //...
-  loginRequestTemplate: {
-    context: readFileSync('./loginResponseTemplate.xml'),
-  }
+	//...
+	loginRequestTemplate: {
+		context: readFileSync("./loginResponseTemplate.xml"),
+	},
 });
 ```
 
 In SP configuration, `loginRequestTemplate` is the template of SAML Request, it can be either file name or XML string. This is the default template we've used in our module.
 
 ```xml
-<samlp:AuthnRequest 
-    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"     
-    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" 
-    ID="{ID}" 
-    Version="2.0" 
-    IssueInstant="{IssueInstant}" 
-    Destination="{Destination}" 
-    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" 
+<samlp:AuthnRequest
+    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
+    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
+    ID="{ID}"
+    Version="2.0"
+    IssueInstant="{IssueInstant}"
+    Destination="{Destination}"
+    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
     AssertionConsumerServiceURL="{AssertionConsumerServiceURL}">
-    
+
     <saml:Issuer>{Issuer}</saml:Issuer>
-    <samlp:NameIDPolicy 
-        Format="{NameIDFormat}" 
+    <samlp:NameIDPolicy
+        Format="{NameIDFormat}"
         AllowCreate="{AllowCreate}"/>
-        
+
 </samlp:AuthnRequest>
 ```
 
 When you apply your own template, remember to do custom tag replacement when you send out the request. `replaceTagFromTemplate` is just the name here to illustrate but it's not fixed.
 
 ```javascript
-router.get('/spinitsso-redirect', (req, res) => {
-  
-  const { id, context } = sp.createLoginRequest(idp, 'redirect', loginRequestTemplate => {
-    // Here is the callback function for custom template
-    // the input parameter is the value of loginRequestTemplate
-    // The following is the input parameter of rcallback in different actions
-    // sp.createLoginRequest -> loginRequestTemplate
-    // sp.createLogoutResponse -> logoutResponseTemplate
-    // idp.createLoginResponse -> loginResponseTemplate
-    // idp.createLogoutRequest -> logoutRequestTemplate
-    // replaceTagFromTemplate is a function to do dynamically substitution of tags
-    return replaceTagFromTemplate(loginRequestTemplate);
-  });
-
-  return res.redirect(context);
-  
+router.get("/spinitsso-redirect", (req, res) => {
+	const { id, context } = sp.createLoginRequest(idp, "redirect", {
+		customTagReplacement: (loginRequestTemplate) => {
+			// Here is the callback function for custom template
+			// the input parameter is the value of loginRequestTemplate
+			// The following is the input parameter of rcallback in different actions
+			// sp.createLoginRequest -> loginRequestTemplate
+			// sp.createLogoutResponse -> logoutResponseTemplate
+			// idp.createLoginResponse -> loginResponseTemplate
+			// idp.createLogoutRequest -> logoutRequestTemplate
+			// replaceTagFromTemplate is a function to do dynamically substitution of tags
+			return replaceTagFromTemplate(loginRequestTemplate);
+		},
+	});
+
+	return res.redirect(context);
 });
 ```
 

src/binding-redirect.ts

@@ -83,10 +83,11 @@ function buildRedirectURL(opts: BuildRedirectConfig) {
 * @param  {function} customTagReplacement      used when developers have their own login response template
 * @return {string} redirect URL
 */
-function loginRequestRedirectURL(entity: { idp: Idp, sp: Sp }, customTagReplacement?: (template: string) => BindingContext): BindingContext {
+function loginRequestRedirectURL(entity: { idp: Idp, sp: Sp, relayState?: string }, customTagReplacement?: (template: string) => BindingContext): BindingContext {
 
   const metadata: any = { idp: entity.idp.entityMeta, sp: entity.sp.entityMeta };
   const spSetting: any = entity.sp.entitySetting;
+  const relayState = entity.relayState === undefined ? spSetting.relayState : entity.relayState;
   let id: string = '';
 
   if (metadata && metadata.idp && metadata.sp) {
@@ -119,7 +120,7 @@ function loginRequestRedirectURL(entity: { idp: Idp, sp: Sp }, customTagReplacem
         isSigned: metadata.sp.isAuthnRequestSigned(),
         entitySetting: spSetting,
         baseUrl: base,
-        relayState: spSetting.relayState,
+        relayState: relayState,
       }),
     };
   }

src/entity-sp.ts

@@ -23,7 +23,7 @@ import { flow, FlowResult } from './flow';
 /*
  * @desc interface function
  */
-export default function(props: ServiceProviderSettings) {
+export default function (props: ServiceProviderSettings) {
   return new ServiceProvider(props);
 }
 
@@ -54,35 +54,74 @@ export class ServiceProvider extends Entity {
   * @param  {string}   binding                   protocol binding
   * @param  {function} customTagReplacement     used when developers have their own login response template
   */
+  public createLoginRequest(
+    idp: IdentityProvider,
+    binding?: string,
+    customTagReplacement?: (template: string) => BindingContext
+  ): BindingContext | PostBindingContext | SimpleSignBindingContext;
+
+  /**
+  * @desc  Generates the login request for developers to design their own method
+  * @param  {IdentityProvider} idp               object of identity provider
+  * @param  {string}   binding                   protocol binding
+  * @param  {object}   options                   optional parameters
+  * @param  {function} options.customTagReplacement     used when developers have their own login response template
+  * @param  {string}   options.relayState                optional relay state
+  */
+  public createLoginRequest(
+    idp: IdentityProvider,
+    binding?: string,
+    options?: {
+      customTagReplacement?: (template: string) => BindingContext;
+      relayState?: string;
+    }
+  ): BindingContext | PostBindingContext | SimpleSignBindingContext;
+
   public createLoginRequest(
     idp: IdentityProvider,
     binding = 'redirect',
-    customTagReplacement?: (template: string) => BindingContext,
-  ): BindingContext | PostBindingContext| SimpleSignBindingContext  {
+    optionsOrCustomTagReplacement?:
+      | { customTagReplacement?: (template: string) => BindingContext; relayState?: string; }
+      | ((template: string) => BindingContext)
+  ): BindingContext | PostBindingContext | SimpleSignBindingContext {
     const nsBinding = namespace.binding;
     const protocol = nsBinding[binding];
+
+    // Handle both old signature (function) and new signature (options object)
+    let customTagReplacement: ((template: string) => BindingContext) | undefined;
+    let relayState: string | undefined;
+
+    if (typeof optionsOrCustomTagReplacement === 'function') {
+      // Old signature: third parameter is customTagReplacement function
+      customTagReplacement = optionsOrCustomTagReplacement;
+    } else if (optionsOrCustomTagReplacement && typeof optionsOrCustomTagReplacement === 'object') {
+      // New signature: third parameter is options object
+      customTagReplacement = optionsOrCustomTagReplacement.customTagReplacement;
+      relayState = optionsOrCustomTagReplacement.relayState;
+    }
+
     if (this.entityMeta.isAuthnRequestSigned() !== idp.entityMeta.isWantAuthnRequestsSigned()) {
       throw new Error('ERR_METADATA_CONFLICT_REQUEST_SIGNED_FLAG');
     }
 
     let context: any = null;
     switch (protocol) {
       case nsBinding.redirect:
-        return redirectBinding.loginRequestRedirectURL({ idp, sp: this }, customTagReplacement);
+        return redirectBinding.loginRequestRedirectURL({ idp, sp: this, relayState }, customTagReplacement);
 
       case nsBinding.post:
         context = postBinding.base64LoginRequest("/*[local-name(.)='AuthnRequest']", { idp, sp: this }, customTagReplacement);
         break;
 
       case nsBinding.simpleSign:
         // Object context = {id, context, signature, sigAlg}
-        context = simpleSignBinding.base64LoginRequest( { idp, sp: this }, customTagReplacement);
+        context = simpleSignBinding.base64LoginRequest({ idp, sp: this }, customTagReplacement);
         break;
 
       default:
         // Will support artifact in the next release
         throw new Error('ERR_SP_LOGIN_REQUEST_UNDEFINED_BINDING');
-    } 
+    }
 
     return {
       ...context,