Skip to content

SAML settings for apps

You can find the SAML protocol related settings under protocol section of the selected SAML application.

SAML settings

Basic settings

Assertion consumer service URLs (ACS URLs)

The Assertion Consumer Service (ACS) URL determines where Asgardeo will send the SAML response. An application can have multiple ACS URLs. SAML authentication response and logout response are sent to one of the ACS URLs configured.

Default assertion consumer service URL (Default ACS URL)

Since an application can register multiple assertion consumer URLs, you need to pick one of them as the Default Assertion Consumer URL. If there is only one ACS URL, it will be taken as the Default ACS URL.

Note

  • If no ACS URL is given in the authentication request, Asgardeo sends the response to the default ACS URL.
  • If an ACS URL is given in the authentication request, and it matches with one of the registered ACS URLs, the Asgardeo sends the response to the ACS URL sent in the request (the matched one).

IdP entity ID alias

This value can override the default Identity Provider (IdP) entity ID (accounts.asgardeo.io/t/{organization_name}). The IdP entity ID is used as the saml2:Issuer of the SAML response that is generated by Asgardeo. This should be a valid URI/URL.

<saml2:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"
                  xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                  >accounts.asgardeo.io/t/{organization_name}</saml2:Issuer>

Advanced settings

Request Validation

Enable request signature validation

Specifies whether Asgardeo must validate the signature of the SAML authentication request and the SAML logout request that are sent by the application.

Note

This option will only be available after a certificate is uploaded. Learn more about certificates.


Response Signing

Sign SAML response

Specifies whether the SAML responses generated by Asgardeo should be signed.

Digest algorithm

Used as the digest algorithm in authentication response and logout response. This is specified as the DigestMethod algorithm in the Signature element.

Signing algorithm

Used as the signing algorithm to sign the authentication response and logout response. This specifies the SignatureMethod algorithm to be used in the Signature element in the SAML response.

Single Sign-On Profile

Bindings

Specifies the mechanisms to transport SAML messages in communication protocols. Bindings define how SAML request-response protocol messages can be exchanged between identity provider and SAML application via HTTP transport.

Asgardeo by default supports the following bindings: - HTTP Post - HTTP Redirect

Enable IdP initiated SSO

Specifies whether to initiate Single Sign-On (SSO) from the IdP instead of the application. If this is selected, a service provider is not required to send the SAML2 request. The Request URL is used by the IDP to forward the users directly to the service provider.

Request

https://api.asgardeo.io/t/{organization_name}/samlsso?spEntityID={sp_issuer}

Sample request

https://api.asgardeo.io/t/bifrost/samlsso?spEntityID=https://sample.app/saml/sp

Note that, you need to encode the URLs before calling the single signon service.

Assertion

Name ID format

Specifies the name identifier format that is used to exchange information regarding the user in the SAML assertion.

For SSO interactions, you can configure the following types of NameID formats.

  • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
  • urn:oasis:names:tc:SAML:2.0:nameid-format:transient
  • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
  • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
  • urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
  • urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName
  • urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos
  • urn:oasis:names:tc:SAML:2.0:nameid-format:entity

Specifies the name identifier format that the application wants to receive in the subject of an assertion from Asgardeo.

Asgardeo uses urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress as the default name identifier.

<saml2:Assertion ID="_1fc418b1886158a8c239f9ee5205718b"
                     IssueInstant="2021-07-07T08:28:30.228Z"
                     Version="2.0"
  xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
                     >
  <saml2:Subject>
  <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">[email protected]</saml2:NameID>
  <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
   <saml2:SubjectConfirmationData InResponseTo="mjagocahejhadgbaldpgpoipaghellkjkdnpilcp"
                                                   NotOnOrAfter="2021-07-07T08:33:30.228Z"
                                                   Recipient="http://localhost:8080/sample-app/home.jsp"
                                                   />
  </saml2:SubjectConfirmation>
 </saml2:Subject>
</saml2:Assertion>

Audiences

Specifies the audiences, to whom this SAML assertion is intended.

The issuer of the application will be added as the default audience

<saml2:Assertion
  ID="_1fc418b1886158a8c239f9ee5205718b"
  IssueInstant="2021-07-07T08:28:30.228Z"
  Version="2.0"
  xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
>
  <saml2:AudienceRestriction>
        <saml2:Audience>https://sampleapp.com/saml/sp</saml2:Audience>
  </saml2:AudienceRestriction>
</saml2:Assertion>


Recipients

Recipient is a URI specifying the entity or location to which Asgardeo can present the assertion.

This attribute may specify the recipient endpoint to which the assertion should be delivered. This attribute is helpful in preventing an intermediary from redirecting the assertion to some other endpoint.

By default, Asgardeo sends ACS URL as the recipient value.

After adding http://localhost:8081/sample-app-new/home.jsp as a recipient:

<saml2:Subject>
            <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">[email protected]</saml2:NameID>
            <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml2:SubjectConfirmationData InResponseTo="jegiegkloeahkcllbnbcohgdeklidegeoiijhado"
                                               NotOnOrAfter="2021-07-07T08:44:45.727Z"
                                               Recipient="http://localhost:8081/sample-app/home.jsp"
                                               />
            </saml2:SubjectConfirmation>
            <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml2:SubjectConfirmationData InResponseTo="jegiegkloeahkcllbnbcohgdeklidegeoiijhado"
                                               NotOnOrAfter="2021-07-07T08:44:45.727Z"
                                               Recipient="http://localhost:8081/sample-app-new/home.jsp"
                                               />
            </saml2:SubjectConfirmation>
        </saml2:Subject>

Enable encryption

Specifies whether to enable encryption for SAML assertion.
To enable encryption, you should configure the certificate of your application. You can configure the certificate from the Certificates section.

Assertion encryption algorithm

The Assertion encryption algorithm you select specifies the symmetric encryption algorithm that is used for encrypting the SAML Assertion.

The following encryption process is enforced by the Assertion encryption algorithm:

  1. First, a SAML2 Key is generated. This key is used for maintaining a secure communication channel with the application.
  2. Asgardeo then uses the generated SAM2 Key value and the symmetric encryption algorithm specified here to encrypt the SAML Assertion.

Key encryption algorithm

The key encryption algorithm you select specifies the asymmetric encryption algorithm that is used for encrypting the SAML2 key.

Asgardeo uses the Public Key of the application (obtained from the certificate) and the asymmetric encryption algorithm specified here to encrypt the SAML2 Key.

Attribute Profile

Enable attribute profile

Specifies whether to include the user's attributes in the SAML assertions as part of the attribute statement. You can configure user attributes by navigating to User Attributes section in the application.


Single Logout Profile

All the settings under this section are related to single-logout. In Single logout, if one application logs out from a browser session, Asgardeo will send logout requests to all the other SAML applications participating in the same browser session.

Enable SLO

Specifies whether you want to enable single-logout to your application. By default, this is disabled for applications.

Logout method

Specifies the logout method that is supported by the application. Asgardeo supports below logout methods:

  • Back Channel logout
  • Front Channel HTTP Redirect
  • Front Channel HTTP Post

Back Channel logout is enabled by default.

Single logout response URL

Specifies the endpoint of the application to where the single logout response should be sent. If you do not specify this URL, Asgardeo will use the Default ACS URL.

Single logout request URL

Specifies the endpoint of the application to where the single logout request should be sent. If you do not specify this URL, Asgardeo will use the Default ACS URL.

IdP initiated single logout

Asgardeo facilitates IdP initiated SAML2 single log out requests. The following parameters can be used with the IdP initiated SLO request:

Request Parameter Description
slo Must have the value “true” to mark the request as an IdP initiated log out request.
spEntityID Value of the parameter should be the SAML issuer value of the application
returnTo Value of the parameter should be the URL which needs to be redirected to, after the log out. If this parameter is present in the request, then the `spEntityID` parameter must also be present.


Enable: Specifies whether to support IdP initiated logout.

Return to URLs: Specifies the URLs to which the user should be redirected after the logout. The returnTo parameter sends in the logout request should match with any of the URL configured as Return to URLs or Default ACS URL.

If Return to URLs is not configured, the returnTo parameter should match with Default ACS URL.

Request

https://api.asgardeo.io/t/{organization_name}/samlsso?slo=true&spEntityID={sp_issur}&returnTo={url}

Sample request

https://api.asgardeo.io/t/bifrost/samlsso?slo=true&spEntityID=https://sample.app/saml/sp&returnTo=http://localhost:8081/sample-app/index.html


Note that, you need to encode the URLs before calling the single logout service.

Certificate

The certificate is used to validate signatures when authentication requests or logout requests from the application are signed. Note that request signature validation should be enabled.
You can either upload your certificate file or copy the contents. Follow the steps given below.

  1. Select Provide Certificate and click New Certificate.

    Upload app certificate

  2. Upload the certificate file or copy the certificate contents

How to convert .crt, .cer or .der to the .pem format?

You can use OpenSSL to convert certificates of other formats to the .pemformat using the following commands.

Convert CRT to PEM

openssl x509 -in cert.crt -out cert.pem
Convert CER to PEM:
openssl x509 -in cert.cer -out cert.pem
Convert DER to PEM:
openssl x509 -in cert.der -out cert.pem