SAML Integration Guide (Okta, etc.)
This guide is designed to assist you in integrating your Identity Provider (IdP) with our product using SAML. Follow these steps to establish a secure authentication flow, enabling your users to access our product seamlessly with their existing credentials.
To begin integrating SAML, ensure you have the following details:
- Single Sign-On (SSO) URL: The URL from your IdP to initiate the login process, such as
https://your-company.com/authorize. - Issuer: The URL identifying the token's issuer, set as
https://your-company.com. - X.509 Certificate: The public key used to verify the authenticity of SAML assertions sent by the IdP.
Authentication Process
Request Phase
The SAML flow begins with the authorization request, redirecting users to the Single Sign-On URL with generated and encoded SAML AuthnRequest sent through query params.
Example authorization request URL:
https://your-company.com/authorize?
SAMLRequest=fZFbT8IwFMe...xMn3w%3D%3D
Example SAMLRequest:
<samlp:AuthnRequest
AssertionConsumerServiceURL="https://your-company.northpass.com/auth/saml/callback"
Destination="https://your-company.com/authorize"
ID="_6437ac63-4834-4694-a42f-c3d82ffda3cb"
IssueInstant="2024-01-01T01:00:00Z"
Version="2.0"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
<saml:Issuer>https://app.schoolkeep.com</saml:Issuer>
</samlp:AuthnRequest>
This request is sent to the Identity Provider’s SSO URL, where the user is prompted to log in.
Callback Request Phase
After successful authentication, the IdP sends an encoded SAMLResponse back to Northpass:
POST https://your-company.northpass.com/auth/saml/callback
Content-Type: application/x-www-form-urlencoded
SAMLResponse=PHNhbWxwOlJ...SZXNwb25zZT4%3D
Example SAMLResponse:
<?xml version="1.0" encoding="UTF-8"?>
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="_2a64c0c1785fc326b29d" InResponseTo="_c1db2017-b152-411c-b73e-af6ff4fe615d" Version="2.0" IssueInstant="2024-01-01T01:00:00.000Z" Destination="https://your-company.northpass.com/auth/saml/callback">
<saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:your-company.com</saml:Issuer>
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
</samlp:Status>
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Version="2.0" ID="_VTVFkWcxZiIhGjNag9mcyn3Dzi43wxFP" IssueInstant="2024-01-01T01:00:00.000Z">
<saml:Issuer>urn:your-company.com</saml:Issuer>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
<SignedInfo>
<CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
<SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
<Reference URI="#_VTVFkWcxZiIhGjNag9mcyn3Dzi43wxFP">
<Transforms>
<Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
<Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
</Transforms>
<DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
<DigestValue>bItk50QMFcNRuiOdY3RjcSIws+ITs+gYzMz28OA5Pt0=</DigestValue>
</Reference>
</SignedInfo>
<SignatureValue>BzbGIU...kv29K51Q==</SignatureValue>
<KeyInfo>
<X509Data>
<X509Certificate>MIIDDTC...YDYesRs=</X509Certificate>
</X509Data>
</KeyInfo>
</Signature>
<saml:Subject>
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">id-12345</saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml:SubjectConfirmationData NotOnOrAfter="2024-01-01T02:00:00.000Z" Recipient="https://your-company.northpass.com/auth/saml/callback" InResponseTo="_c1db2017-b152-411c-b73e-af6ff4fe615d" />
</saml:SubjectConfirmation>
</saml:Subject>
<saml:Conditions NotBefore="2024-01-01T01:00:00.000Z" NotOnOrAfter="2024-01-01T02:00:00.000Z">
<saml:AudienceRestriction>
<saml:Audience>https://app.schoolkeep.com</saml:Audience>
</saml:AudienceRestriction>
</saml:Conditions>
<saml:AuthnStatement AuthnInstant="2024-01-01T01:00:00.000Z" SessionIndex="_Pq0GSaUekDIyIbfJF5nUwBzIKOjQ2AC_">
<saml:AuthnContext>
<saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml:AuthnContextClassRef>
</saml:AuthnContext>
</saml:AuthnStatement>
<saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string">[email protected]</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string">Jane</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string">Doe</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
</saml:Assertion>
</samlp:Response>
Processing the Callback
Validating the SAML Response
The first step in processing the SAML Response is validation. This includes several checks to ensure the authenticity and integrity of the response:
- Signature Validation: We use the IdP’s X.509 certificate to verify that the SAML Response and its assertions are signed by the trusted IdP. This prevents tampering with the response during transmission.
- Issuer Validation: We verify that the response was issued by a trusted Identity Provider by checking the Issuer value inside the SAML Response against a preconfigured list of allowed issuers.
- InResponseTo: We check the InResponseTo attribute of the response to ensure it matches the original AuthnRequest ID that the SP sent during the login request. This prevents replay attacks.
- Destination Validation: The response must have the correct Destination URL, which should match the configured ACS URL on the SP’s side. This confirms that the response was intended for the correct service.
Data extraction from SAML Response
Once the SAML Response is successfully validated in the Callback Phase, the next crucial step is to extract the user’s attributes and user identifier (ID) from the SAML Assertion. These attributes are used by Northpass to map the user’s identity and information to the application’s user database.
The NameID element is usually part of the Subject section in the SAML Assertion. This is the unique identifier for the user in the context of the IdP, and it is critical for the Northpass to map users between the IdP and the application. From within Northpass, the sso_uid will be mapped to the NameID value your IdP provides. Example:
<saml:Subject>
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">id-12345</saml:NameID>
</saml:Subject>
The element contains additional user information, such as the user’s first name, last name, and email, which Northpass needs to map the user profile in its system. Example:
<saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string">[email protected]</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string">Jane</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string">Doe</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
This data creates the user's profile, facilitating a personalized and secure sign-in experience.
Dynamic Group Assignment
Our platform supports dynamic group assignment through custom attributes in the response. This feature allows for seamless user categorization and access management based on predefined groups. To leverage this, include an additional attribute in the AttributeStatement as follows:
<saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string">[email protected]</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string">Jane</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string">Doe</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="Groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string">group1</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string">group2</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
In this structure, the Groups object contains a groups array, which should list the names of the groups as strings. Users will be automatically added to the specified groups in this array upon signing in. This facilitates immediate and appropriate access to resources and functionalities aligned with the user's roles and permissions.
Finally, Northpass redirects the authenticated user to the destination page within the platform.
SAML metadata
To access the SAML metadata you can visit the following endpoint: https://app.northpass.com/auth/saml/metadata.
Updated 2 months ago