SAML settings for apps¶
You can find the SAML protocol related settings under protocol section of the selected SAML application.
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:
- First, a SAML2 Key is generated. This key is used for maintaining a secure communication channel with the application.
- 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.
-
Select Provide Certificate and click New Certificate.
-
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 .pem
format using the following commands.
Convert CRT to PEM
openssl x509 -in cert.crt -out cert.pem
openssl x509 -in cert.cer -out cert.pem
openssl x509 -in cert.der -out cert.pem