What is SAML?
SAML stands for Security Assertion Markup Language and is a standard single sign-on (SSO) format -- essentially exchanging authentication and authorisation data between parties. In SAML, these parties are referred to as the service provider (Award Force) and the identity provider (your system).
Award Force supports both service provider-initiated login, (e.g. a button on the login screen of your platform) and identity provider-initiated login (e.g. a button placed on your intranet or another private site).
SAML is an optional add-on for your account. For more information and pricing, please get in touch.
Setting up SAML
With Award Force
Once SAML has been added to your account, navigate to Settings > Users > Registration > 3rd party authentication and select the SAML checkbox.
You will need to fill in the following details of your identity provider. Note: Award Force is not the identity provider.
- Issuer (a string identifying the IP)
- Single sign-on service URL
- X.509 certificate
With your identify provider
Steps may vary based on your desired provider, and your IT team will likely need to be involved in the configuration, but the key facts to know are:
The provided Name IDs should be persistent.
The integration requires three attributes (firstName, lastName and email) to be present in the authentication response in order to create accounts for users authenticating with SAML.
The SAML response from the identity provider contains an email attribute, which is used to check if an account already exists within Award Force. If it doesn't, a new account is created for the user.
If the email does exist within Award Force, there's an additional step that allows the user to link their existing account with their SAML identity. The user will simply need to input the code that has been emailed to them. For security purposes the code expires in 10 minutes, but can be regenerated if necessary. If a new code is generated, the previous code is voided.
Service Provider Metadata
Once set up is complete, you will see a link under 'Service provider metadata' at the bottom of the Integration tab in your account. Clicking the link will open an XML file in a new tab.
The metadata contained in the XML file is unique to your account. The file contains some details which may be useful for future references, such as entityID URL and the Reply URL (also referred to as the Assertion Consumer Service (ACS) URL). The required attributes: firstName, lastName, email can also be found in the metadata.
The Reply URL always takes the format: https://your_account_URL/saml/callback where 'your_account_URL' will be something.awardsplatform.com or your custom domain if one has been configured.
Need more help? Get in touch!
We're here to help if you need it. Simply get in touch with our Client Success team through one of the methods available at the base of the page.