SAML (Security Assertion Markup Language) connections enable PlusAuth to integrate with external Identity Providers (IdPs) that support the SAML 2.0 protocol. This allows users managed by your organization's existing identity system (like Active Directory Federation Services (ADFS), Okta, Azure AD, or others) to securely authenticate to applications protected by PlusAuth without needing to create separate accounts.
By configuring a SAML connection in PlusAuth, you establish a trust relationship between PlusAuth (acting as a Service Provider - SP) and your chosen SAML IdP. When a user attempts to log in to an application secured by PlusAuth, they can be redirected to your organization's familiar login portal hosted by the SAML IdP. Upon successful authentication at the IdP, a digitally signed SAML assertion containing the user's identity information is sent back to PlusAuth. PlusAuth then validates this assertion and establishes a session for the user, granting them access to the application.
Configuring a SAML connection in PlusAuth typically involves providing metadata or specific configuration details about your SAML IdP, such as its entity ID, sign-in and sign-out URLs, and public signing certificate. You may also need to configure PlusAuth as a trusted Service Provider within your IdP.
sequenceDiagram participant User participant SP participant IdP
User->>SP: Access Resource SP->>SP: Create SAML Request SP-->>User: Redirect to IdP with SAML Request User->>IdP: Send SAML Request IdP->>IdP: Authenticate User IdP-->>User: Send SAML Response (Assertion) User->>SP: Send SAML Response (Assertion) SP->>SP: Validate Assertion SP->>SP: Authenticate User SP-->>User: Grant Access Connection Configuration
Following properties are used for configuring a SAML connection:
| Name | Description | Example |
|---|---|---|
metadata_url | Your SAML IDP's metadata URL. | https://idp.example.com/metadata |
entity_id | Your SAML IDP's entity_id. | https://idp.example.com/entity |
sign_in_url | Your SAML IDP's login URL. | https://idp.example.com/login |
sign_out_enabled | If enabled, when a user logs out from PlusAuth, a SAML logout request will be sent to the SAML IdP. | true |
sign_out_url | Your SAML IdP's sign out URL. | https://idp.example.com/logout |
signing_certificate | The public certificate of your SAML Identity Provider. | MIICajCCAdOgAwIBAgIBADANBgkqhkiG9w0BAQsFAD... (PEM format) |
sign_request | Enable or disable the signing of SAML authentication requests. | true |
sign_request_algorithm | The algorithm to use for signing SAML authentication requests. | sha256 |
request_binding | HTTP binding to use when sending SAML authentication requests. | HTTP-POST |
sign_out_binding | HTTP binding to use when sending SAML logout requests. | HTTP-Redirect |
mappings | Defines how SAML attributes map to PlusAuth user properties. | See User Object Mapping |
User Object Mapping
SAML Identity Providers (IdPs) possess the capability to transmit a variety of user attributes within the SAML assertion. To ensure consistent utilization of this information within PlusAuth, it is necessary to establish a mapping between the attributes contained in the SAML assertion and the corresponding user properties in PlusAuth.
While the mapping of all attributes is not invariably required, certain attributes are essential for proper user identification and system functionality. The following attributes are typically required:
| Configuration | Description |
|---|---|
id | A unique identifier for the user. This is crucial for PlusAuth to correctly identify and manage user accounts across logins. Common SAML attributes used for this are NameID or a unique user identifier provided by the IdP. |
email | The user's email address. This is often required for password reset functionality and other communication purposes. The corresponding SAML attribute is commonly emailaddress or mail. |
The mapping of other attributes is optional; however, it can be advantageous. For instance, if an application utilizes a user's first name, last name, or phone number, the corresponding SAML attributes (e.g., givenname, surname, mobilephone) should be mapped. This practice ensures that user profiles within PlusAuth are automatically populated with data provided by the SAML IdP, thereby enhancing the user experience and mitigating the need for manual data entry.
Default SAML mapping is as following:
{ "id": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", "email": [ "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" ], "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name", "phone_number": "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone", "profile.name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname", "profile.family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname", "profile.gender": "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/gender", "profile.birthdate": "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/dateofbirth", "profile.website": "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/webpage"}