SAML
Configuration
- For a SAML provider setup, create your own Enterprise application under Azure Active Directory and select the option to integrate any other application not found in the gallery.
- Upon creation, head to the Single sign-on page and select SAML. The SAML configuration will prompt for both an Identifier (Entity ID) and a Reply URL (Assertion Consumer Service URL). Copy the required details from the SSO provider form on the FUYL™ Portal into the respective fields. The other fields can be left as empty.
- Head to the SAML Signing Certificate section within the same page and copy the App Federation Metadata Url into the Metadata document form field on the FUYL Portal. Alternatively, the raw Metadata file can be uploaded instead which can be found in the same section labeled as Federation Metadata XML.
- User attributes and claims are already set up by default. Edit the section to view claims to map selected attributes on the FUYL Portal. Claims can also be managed to map other user attributes such as displayname based on your preference. An example of user attribute mappings on FUYL Portal:
- Assign users and groups to the SAML enterprise application to grant access to the FUYL Portal.
Each assigned user will need to select “Sign in with SSO” and enter the SSO Provider name configured in the FUYL Portal, then sign-in with their user principal name.
Assigning custom roles for an SSO user
Before assigning a custom role to an SSO user, app roles will need to be created which can be found via App registrations.
- Create a new app role within your Enterprise Application (configured above) and set the allowed member types to Users/Groups. The value represents the ID of a role listed in the FUYL Portal Roles section located within the accounts page.
- Go to Enterprise applications and select the application used for FUYL Portal.
- Go to Users and groups, select those that require role assignment.
- Use the “edit assignment” button to add the roles required.
- Go to Single sign-on and edit the Attributes & Claims, add a new claim.
- The claim name should be set to the same value as the Roles attribute map (customisable) in the FUYL Portal. The namespace can be ignored.
- Leave the claim source as Attribute and select user.assignedroles from the source attribute dropdown list.
If an invalid role ID is assigned to a user, the SSO login to the FUYL Portal will fail.
If the Roles attribute mapping is not set in FUYL Portal, all SSO users will be granted the default Admin role.
Troubleshooting
SAML assertion signature is invalid
Ensure that the Identifier and Reply URL in Azure are unique amongst your list of enterprise applications as these details cannot be shared with other enterprise applications within your active directory.
Other issues signing in after entering the provider name
Given that the instructions above are followed and the solutions suggested here do not resolve any of your issues, please contact PC Locs support for assistance.
OIDC
Configuration
- For an OIDC provider setup, create a new App registration application under Azure Active Directory. On the register form, copy the callback URL from the SSO provider form on the FUYL Portal into the Redirect URI field. Leave the application type as Web as Single-page application is not supported.
- Once created, copy the Application client ID into the client ID field of the SSO provider form.
- Create a new client secret and set an expiry based on your preference. Copy the value into the client secret of the SSO provider form. Please note that the secret will have to be regenerated after it expires to persist SSO user access.
- Use any of the following issuers as the domain with the Directory tenant ID of the OIDC application. The issuer to use can be verified by checking the OpenID Connect metadata document under Endpoints.
- https://login.microsoftonline.com/{tenantID}/v2.0
- https://sts.windows.net/{tenantID}
- After the OIDC SSO provider has been configured on both FUYL Portal and Microsoft Azure, users in the SSO directory will now be able to sign-in with their full user principal name. However, owners of the OIDC application cannot sign-in with SSO.
Attribute mappings
- Authorising the profile scope will map the name user attribute to the FUYL Portal.
- Authorising the email scope will map the email user attribute to the FUYL Portal. Under Token configuration of the OIDC application, add an optional email claim with either ID or access token. The API permission for accessing the email address will be delegated automatically upon creation.
- Authorising the roles scope will map the assigned roles to the FUYL Portal.
Assigning custom roles for an SSO user
Before assigning a custom role to an SSO user, app roles will need to be created which can be found via App registrations.
- Create a new app role and set the allowed member types to Users/Groups. The value represents the ID of a role listed in the FUYL Portal Roles section located within the accounts page.
- Go to Enterprise applications and select the application used for FUYL Portal.
- Go to Users and groups, if there are users added already, edit the selected user(s) and select a role.
- Users who login to the FUYL Portal will be granted limited access based on the permissions set for the assigned role.
If an invalid role ID is assigned to a user, the SSO login to the FUYL Portal will fail.
If the roles scopes is not authorised, all SSO users will be granted the default Admin role.
Troubleshooting
User email address is not mapped after authorising scope and adding optional claims
Given the ID or access token type is selected for the claim, ensure the email claim is selected and not any of the verified emails. This may take a few moments before the FUYL Portal registers the email attribute on user sign-in.
Issues signing in after entering the provider name
In most cases, this error occurs when there is a misconfiguration in the setup process. Try any of the following solutions and if the problem persists, please contact FUYL support for further assistance:
Use the alternate issuer as the domain if there are problems with the first option.
Ensure the user principal name is used on the Microsoft sign-in page. This can be verified by viewing the user details within the provider's user directory.
The OIDC application type has to be web as other types are unsupported.
Ensure a valid client secret is set for the SSO provider in the FUYL Portal.
First name and last name
These user attributes are no longer supported for an OIDC provider in the FUYL Portal. SAML is the preferred option if name is not mapped for OIDC.