In this tutorial, you will learn how to configure a SAML application using an identity provider (IdP) that is not listed among the officially supported providers on the Axur Platform — in other words, an IdP categorized as "Other." The process follows steps common to most IdPs and can be adapted according to the options available in your provider. The goal is to enable secure and simplified SSO login, allowing your users to access the platform with a single authentication.
Table of Contents
Before you start
We will now provide a tutorial that can assist you when creating a new SSO application (using the SAML protocol) for the Axur Platform. It is important to highlight that on our platform, we have some “approved” providers (i.e., they have our trust and reliability to provide this functionality for our users), as well as specific tutorials for configuring SSO on these providers.
Although the order may vary slightly depending on your provider, the sections below represent a typical sequence that works across most environments.
Groups, users, and assignments
In all Axur Platform SSO application creation tutorials, there is the notion of users and groups. After all, the provider is where all your user information will be stored, in addition to the groups to which they belong.
Creating a group (optional)
This section is optional. Groups can be managed within the Axur Platform if you wish. Therefore, if you desire, you can skip the sections on Creating a group, Assigning a group to a user, and Mapping user groups
You can create groups with the exact name that the Axur Platform expects.
You can create two groups. One will have an easily identifiable name (Axur Platform Viewer, for example), and the other will be the name expected by the Axur Platform (one-viewer, in the example). Then, in your provider, you will need to create a Rule that associates all users from the easily identifiable group to the group expected by the platform. This strategy is purely for organizational purposes, as you may have multiple applications with many different groups.
Observation: It is of extreme importance that group names comply with the determined pattern. More specifically, a new group must contain the values from the table as a suffix:
Group |
|
|
|
|
|
In this sense, group values like Axur-one-manager and ClientX-one-expert are valid, but Axur-manager and ClientX-analyst are not, because they do not include the expected suffixes.
Refer to the specific tutorials if you have questions about how to do this.
Creating a user
You will need to create users on your provider. Make sure that the following information is present for every user you create. This is fundamental for the process to work:
First Name
Last Name
Email
Ensure these fields are correctly filled; otherwise, mappings may fail during authentication.
Assigning a group to a user (optional)
This section is optional. Groups can be managed within the Axur Platform if you wish. Therefore, if you desire, you can skip the sections on Creating a group, Assigning a group to a user, and Mapping user groups
If you decided to create groups in the provider, you need to add the users you created to those groups. Make sure your group names are correct, and the users are inside the desired groups, otherwise SSO won’t work correctly.
Creating a new application
In your provider, create a new application that will be responsible for providing your user data to the Axur Platform.
Make sure your application is using the SAML protocol; this will be fundamental for correct operation.
Enter data such as name, application description, and perhaps an icon to represent it.
Generally, this concludes the application creation section.
Obtaining provider data
When using an identity provider, it is necessary to obtain some information that can tell the Axur Platform who it will be communicating with and whether its information is secure and reliable. This information is called Provider Metadata.
You can download an
.xmlfile containing all the necessary information to identify the provider. Generally, this is one of the simplest options, as everything is contained in the file, and nothing needs to be copied. If this is your case, download the file and set it aside for future use.Some providers offer a link that points to this metadata. If this is your case, copy the link and set it aside for future use.
We will use this data later when we configure SSO on the Axur Platform.
Sending Axur Platform data to the provider
The provider needs to know who it will be communicating with for the SSO process to work smoothly. In this sense, it is also important that the provider receives the data from the Service Provider, in this case, the Axur Platform.
Generally, providers usually ask for the following data. We indicate in the Field which are usually mandatory and which may be optional.
Field | Value |
ACS URL (Usually Mandatory) | |
Entity ID (Usually Mandatory) |
|
Logout URL (Usually Optional) |
Some providers may ask for a metadata file, which usually contains all this information mentioned above. If this is the case, you can use the following URL:
https://api.axur.com/gateway/1.0/saml-proxy/saml/metadata
Find the section responsible for containing the Service Provider data and fill in the necessary fields.
Mapping user attributes
By using a our provider, we are leveraging the credentials that are already stored and managed by the provider, and these credentials are stored in the format defined by the provider. However, to communicate with the Axur Platform using SAML, it’s necessary that user data is sent in a standardized way. Think of it this way: We need to ensure that the Axur Platform always receives the user’s email attribute in the same format regardless of the provider the data comes from. Different providers store their data in different ways, and mappings solve this problem!
Providers usually offer a selectable menu to determine the Field values (see table). The content may even be written differently (Primary Email in provider X, and user.email in provider Y, for example), but the logic remains the same. Other providers may even include some correct mappings already, requiring only the removal of one or two. In general, it is important that you define the Maps to fields of the mappings to contain the following values:
Field | Maps to |
Primary Email | |
First name | |
Last name |
Mapping user groups (Optional)
This section is optional. Groups can be managed within the Axur Platform if you wish. Therefore, if you desire, you can skip the sections on Creating a group, Assigning a group to a user, and Mapping user groups
Just like user attributes, we also have groups, which bring users together according to some specific criteria. These groups are created by the administrator in the provider, and as explained in the previous section, it is necessary to create a mapping so that this data is transmitted to the Axur Platform in a standardized way, regardless of the provider.
Following the logic of user attribute mappings from the previous section, we need to do something similar with groups. Generically, you need to create mappings following this pattern:
Group | Mapping |
| |
| |
|
The configuration style may vary from provider to provider. Some providers have a group search menu, so you can add all the necessary ones and then enter the URL once; others do not need the URL, but only the value Group; others allow a single URL to be entered, along with a generic pattern like one-.*, and so on.
Refer to the specific tutorials if you have questions about how to do this.
Assigning groups/users to the application
Now all that remains is to assign users or groups to the new application you created. In this case, the necessary actions will depend on your choice:
If you created groups via the provider, add these groups to the new application and ensure they are enabled. This will allow all users contained in these groups to access the application!
If you did not create groups via the provider, simply assign the desired users directly to the application.
Some common errors
The Service Provider (SP) information (Axur Platform in this case). Verify the data from the corresponding section and ensure they are the same.
The Identity Provider (IdP) information. Verify that the file you downloaded here is not altered.
The application access information. Verify that the correct groups or users have been assigned to the application.
Specific errors
Error | Description | How to Resolve |
Non Authorized IdP or expired IdP login | Unauthorized IdP or expired session | Check the Federation Metadata and the IdP. |
Missing value for string parameter [email claim] | Missing or empty email claim | Make sure the email attribute is correctly configured in the IdP. |
Redirection error | Incorrect endpoint URL in the IdP | Check whether the endpoints are correctly configured. |
Local entity is not the intended audience of the assertion in at least one AudienceRestriction | The assertion was not intended for the SP | Check if the |
Authentication statement is too old to be used with value {date} | The authentication statement has expired | The IdP session duration exceeds 7 days. Contact support to adjust it. |
Validation of protocol message signature failed | The signature of the SAML message is invalid | Verify that the Federation Metadata was correctly provided. |
This concludes the necessary configurations in the provider. Return to the configuration guide on the platform to finalize the creation of your application.
If you have any questions, feel free to reach out at [email protected] 😊