--- title: "Security Assertion Markup Language (SAML)" diataxis: how-to applies_to: product: "nirmata-control-hub" audience: ["platform-engineer"] last_updated: 2026-03-25 url: https://docs.nirmata.io/docs/control-hub/identity-access/security-assertion-markup-language-saml/ --- By default, Nirmata uses a self-signed certificate for SAML signatures, as trust between entities is established externally. If your organization requires CA-signed certificates, you can configure them in SAML. **NOTE:** You can optionally provide a custom certificate to be used for SAML signatures. --- ## Single Sign-On with SAML For Enterprise accounts, Nirmata supports Single Sign-On (SSO) with SAML 2.0. This feature allows enterprise administrators to manage their users in a secure and easy manner. For example, when an employee is on-boarded to, or leaves, the enterprise the administrators can enable, or disable, their account in a single place for all enterprise services. This feature also makes life easier for enterprise users as they can authenticate once, and access all enabled services without managing separate passwords and accounts. SAML (Security Assertions Markup Language) is a protocol that defines how systems can exchange security data. The following references are useful in understanding SAML: - [SAML 2.0 - Wikipedia](https://en.wikipedia.org/wiki/SAML_2.0) - [SAML Introduction - XML.org](http://saml.xml.org/wiki/saml-introduction) The SAML protocol is defined at: [Security Assertion Markup Language (SAML) V2.0 Technical Overview - OASIS](https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html). Although SAML is a complex protocol, Nirmata makes it extremely easy to set up and manage. Here are the detailed steps: 1. In your Account view ([Settings, Account](https://www.nirmata.io/webclient/#account)) select the option \"Enable Single Sign-On with SAML\": ![image](/images/SAML-1.png) 2. This option provides a dialog where you can upload the SAML metadata file of your Identity Provider (IdP) e.g. ADFS 3.0. Or, you can manually configure your IdP settings. SAML IdP Metadata import: ![image](/images/SAML-2.png) SAML IdP manual configuration: ![image](/images/SAML-3.png) 3. Next, export your account's Nirmata SAML Service Provider (SP) metadata and import that into your IdP. To export the SP Metadata go to [Settings - SAML 2.0](https://www.nirmata.io/webclient/#identityProvider) and click on the View SP Metadata option. You can then copy the metadata or download it to a file. ![image](/images/SAML-4.png) To complete the setup, you can now import the SAML SP Metadata into your IdP. If you are using Microsoft AD FS (Active Directory Federation Services) follow the steps at [Setup AD FS for use with Nirmata](https://docs.nirmata.io/docs/control-hub/identityaccess/security-assertion-markup-language-saml/ad-fs-setup-with-nirmata/) to configure ADFS for SSO with Nirmata. That's it! You now have SAML fully configured! **Note:** By default, self-signed certificates are used to sign and encrypt the data. In order to use CA signed certificates, see [Using CA signed SAML signature certificates](https://docs.nirmata.io/docs/control-hub/identityaccess/security-assertion-markup-language-saml/using-ca-single-saml-signed-certificates/). --- ## Single Sign-On with SAML (AWS SSO) You can use AWS SSO as a SAML SSO provider. In AWS SSO, you can set up Nirmata as a custom application by following the instructions here: [Custom SAML 2.0 applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/samlapps.html) ## Configure AWS SSO as SAML provider for Nirmata 1. Go to 'Applications' in AWS SSO console and click on 'Add a new application' and then click on 'Add a custom SAML 2.0 application'. 2. Set the Display name to 'Nirmata'. 3. Click on the 'Download' link next to 'AWS SSO SAML metadata file' to download the AWS SSO SAML Metadata XML. 4. In Nirmata, go to Identity & Access -> SAML and click on the button "Enable SAML for federated identity management and single sign-on (SSO)". 5. This launches a dialog where you can upload the AWS SSO SAML Metadata XML file that you downloaded in step 3. 6. Now, export your Nirmata account's SAML Service Provider metadata by clicking on the "View SP Metadata" and downloading it. 7. Next, you can import the SP metadata file into the Nirmata application configuration in AWS SSO by clicking on the 'Browse...' button and selecting the file. 8. Save the changes to complete the creation of the Nirmata SAML 2.0 application. 9. Next, go to the 'Attribute mappings' tab in the AWS SSO -> Nirmata configuration and make the following changes: 1. For the Subject attribute, add ${user:email} in the Mapping column and select 'unspecified' option as the Format 2. Also, add a new attribute mapping with attribute name 'email', Mapping as ${user:email} and Format as 'unspecified' 10. Save changes to complete the AWS SSO setup. 11. Finally, you need to once again download the 'AWS SSO SAML metadata' XML from the AWS SSO -> Nirmata Configuration tab. Import the AWS SSO SAML metadata XML into Nirmata by clicking on the Edit icon in the "SAML Identity Provider (IdP) Settings" section. That's it! You now have SAML fully configured! Next, add users that need access to Nirmata in the AWS SSO console and verify that SAML works. **Note:** Please make sure you have at least one user with 'Local' authentication in Nirmata to avoid being locked out of your account in case SAML based authentication is not available. --- ## Single Sign-On with SAML (Azure AD) You can use Azure AD as SAML SSO provider. In Azure, you can setup Nirmata as an Enterprise Application by following the instructions here: [Set up SAML-based single sign-on (SSO) for an application in your Azure Active Directory (Azure AD) tenant](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-setup-sso) To complete the Azure AD setup, follow these steps. 1. In Nirmata, go to SAML view ([Identity and Access, SAML](https://www.nirmata.io/webclient/#saml)) and click on the button \"Enable SAML for federated identity management and single sign-on (SSO)\" 2. This launches a dialog where you can upload the Federation Metadata XML file for Azure AD. You can [download the Federation Metadata XML file for Azure AD here.](https://login.microsoftonline.com/common/FederationMetadata/2007-06/FederationMetadata.xml) 3. Now, export your Nirmata account's SAML Service Provider (SP) metadata by clicking on the \"View SP Metadata\" and downloading it. Next you can import the metadata into your Azure AD application created for Nirmata earlier. 4. To complete the setup, you need to download the Federation Metadata XML from the Azure AD application. You can find it in the \"SAML Signing Certificate\" section. Import the Federation Metadata XML into Nirmata by clicking on the Edit icon in the "SAML Identity Provider (IdP) Settings" section. Thats it! You now have SAML fully configured! Next, add users that need access to Nirmata in the Azure AD application and verify that SAML works. **Note:** Please make sure you have at least one user with 'Local' authentication in Nirmata to avoid being locked out of your account in case SAML based authentication is not available. ### Sync Azure groups and roles with Nirmata teams You can sync users in Azure groups with teams in Nirmata automatically, and user permissions can be mapped to individual teams. To accomplish this, you can use groups and roles in Nirmata and create mappings for them in your Azure AD setup. Here are the steps: 1. In Nirmata, go to Settings > SAML and look for the following attributes - "Groups Attribute Name" ('groups' by default) and "Role Attribute Name" ('role' by default). You can use them to map groups and roles to Nirmata teams and roles. 2. In your Azure AD setup, go to Enterprise Applications > "Your AD application" and select Single-Sign-on configuration. Under that menu, select and edit **User Attributes & Claims** menu. 3. Add an attribute called groups and map it to your respective Azure groups (e.g. user.department) and save it. 4. Similar mapping can be accomplished for the role attribute. 5. By default, role will map to DevOps role in Nirmata. Now, as users from different groups login, their respective groups will show up under Nirmata as teams, and appropriate access settings can be configured for those teams. --- ## Using CA signed SAML Signature Certificates To use CA signed SAML signature certificates: 1. Add the certificates in the Add SAML SP Settings section. ![image](/images/settings-sp-data.png) 2. Download your account's Nirmata SAML Service Provider (SP) metadata and import it into your IdP. To export the SP Metadata: 1. Go to [Settings - SAML 2.0](https://www.nirmata.io/webclient/#IdentityAccess). 2. Click on the **View SP Metadata** button. You can then copy the metadata or download it as a file. To complete the setup, import the SAML SP Metadata into your IdP. --- ## Enable SAML SSO for a User Nirmata allows you to control the identity provider (IdP) method for individual user accounts. This provides flexibility in managing a mix of service accounts and accounts managed using a central SAML or OIDC-based IdP. ## Enabling Single Sign-On with SAML To enable SAML SSO: 1. Click Identity & Access > SAML. 2. Click the **Key** icon in the SAML view. ![image](/images/identity_enableSAML.PNG) The Add SAML SP Settings dialog appears. ![image](/images/identity_addSAML_SP_Settings.PNG) 3. Enter the *Public Key* and *Private Key* in the Add SAML SP Settings dialog, and click **OK**. ![image](/images/identity_editTeams.PNG) --- ## Setup AD FS for Use with Nirmata This section provides instructions on how to set up Microsoft AD FS (Active Directory Federation Services) as a SAML Identity Provider (IdP). Before you set up ADFS, you must first enable SAML SSO in Nirmata, import the IdP Metadata into Nirmata, and export the SP Metadata. You must also copy or transfer the SP Metadata XML file to your AD FS server. Setting up ADFS involves three steps (the following steps use Windows Server 2012 R2 and ADFS 3.0): 1. Import the SP Metadata into ADFS On your ADFS host open the Server Manager tool and select the **AD FS Management** option: ![image](/images/adfs-1.png) In the AD FS Management window, navigate to Trust Relationships -\> Relying Part Trusts and select **Add Relying Party Trust** from the right Actions panel: ![image](/images/adfs-2.png) Select the SP Metadata XML file that you exported from Nirmata: ![image](/images/adfs-3.png) Provide a Display Name: ![image](/images/adfs-4.png) If your organization uses Multi-factor Authentication (MFA), you can enable it. Otherwise, leave it disabled: ![image](/images/adfs-5.png) On the next screen, select **Permit all users to access this relying party**: ![image](/images/adfs-6.png) Since we imported the SP settings from the Metadata file, simply click next on the **Ready to Add Trust** screen: ![image](/images/adfs-7.png) Make sure that the **Open the Edit Claim Rules dialog\...** option is checked and close the wizard: ![image](/images/adfs-8.png) Proceed to configure a SAML claim below. 2. Setup a SAML Claim Rule for Nirmata Nirmata requires that the SAML Name ID field contain the email address of the principal. You can enable this by configuring a SAML Claim Rule in ADFS. Click on **Add Rule..** to configure the claim: ![image](/images/adfs-9.png) Select **Send LDAP Attributes as Claims** and click next: ![image](/images/adfs-10.png) Enter a name for the claim rule, such as "email address". Then select **Active Directory** as the Attribute Store. In the mapping section, select **E-Mail-Addresses** as the LDAP Attribute and **Name ID** as the Outgoing Claim Type. ![image](/images/adfs-11.png) Click **Finish** to add the claim and then **OK** to exit the Edit Claim Rules dialog. 3. Allow SAML signature certificates to be self-signed In a SAML message exchange, X.509 Certificates with public and private key pairs are used to sign and encrypt the data. Since the keys are exchanged via Metadata and the SAML messages are exchanged over a secure (TLS) connection, there is no benefit in using CA signed certificates for signing. Nirmata generates self-signed certificates for SAML signatures and encryption. You must setup AD FS to not require CA certificates for SAML signing and encryption. You can manage these settings using PowerShell as described below. Check your current settings using the PowerShell command: Get-AdfsRelyingPartyTrust | Select-Object Identifier, SigningCertificateRevocationCheck, EncryptionCertificateRevocationCheck ![image](/images/adfs-12.png) Use this PowerShell command to disable CA certificate checks for Nirmata: Get-AdfsRelyingPartyTrust -Identifier https://www.nirmata.io/security/api/ | Set-AdfsRelyingPartyTrust -SigningCertificateRevocationCheck None -EncryptionCertificateRevocationCheck None ![image](/images/adfs-13.png) You should now be able to navigate to your AD FS login page and select Nirmata (Nirmata Cloud Services). This will initiate the SAML SSO exchange and authenticate your users with AD FS. ![image](/images/adfs-14.png) Alternatively, you can also sign in using your email address at: .