SAML Authentication

Identity Panel suite supports custom SAML authentication for scenarios that are not compatible with Azure OIDC. Example scenarios include:

1. Authenticating against multiple source directory types, e.g. Azure AD and Azure AD GCC High
2. Integrating with global enterprise authentication solution other than Azure
3. Federated and/or internet facing authentication when using on-premises hosting
4. Federate against multiple IDPs (e.g. an enterprise provider, and a partner provider)

Pre-requisites

To configure custom SAML authentication you must have the following prerequisites:

1. Identity Panel Suite v6.1 or later
2. If self-hosting: Add configuration key "Auth:EnableSAMLExtenion": "true"
   
3. If self-hosting: Connect to MongoDB, open the Tenant collection, and edit your Tenant record to add custom URL bindings by setting the idph (Identity Panel), svph (Service Panel), and acph (Access Panel) array properties:
   
4. If cloud-hosted request enablement of SAML Extension via a support ticket at Service Desk
5. Have a compliant SAML 2 Identity Provider with access to add Service Provider integrations
6. Add SAML Configuration strips to Identity Panel / Settings / Extensions for each host that will be authenticating via SAML (e.g. Service Panel and Identity Panel).

Configuring SAML Authentication

Use the following steps to add a custom SAML integration.

1. Go to Identity Panel / Settings / Extensions. Select and add a SAML Configuration strip:
   
2. Give the configuration a name, and select the desired hostname as the Entity Id. You must have custom hosts bound on your tenant record to see a selectable entity id.
3. Under Certificates create a new certificate and set usage to Any (or create a separate certificate for each usage).
   
4. Save your progress and refresh the page. This will populate the URL listing, and allow you to set certificate details.
5. NOTE: You can add multiple certificates in both the certificates and partners section. This may be used to enable zero-downtime certificate rollover/update with partner identity providers.
6. Certificate Option 1
   1. Press the Generate Certificate button to auto-generate a self-signed certificate with a two-year expiration. This will populate the certificate string, pre-populate a long random encrypted password (which is never displayed), and displays details like Subject, Thumbprint etc.
      
   2. The public key may be obtained for Identity Providers by copying out the base64 cer encoded value from the Public Key label, or by pressing the Download Metata button on the SAML configuration.
      
7. Certificate Option 2
   1. Obtain or generate a certificate as a pfx including the private key. Convert the PFX to Base64, paste the base64 in the Certificate String field, and paste the PFX password in the password field.
   2. Save settings (this will read the certificate and fill-in other fields like Subject, Thumbprint, Expires, etc.
8. Configure each Identity Provider as a partner by populating the various URLs and certificates. This may be done manually or by downloading a metadata file.
   NOTE: The metadata file will not include the Sign-on URL for IdP initiated login, so you must copy this from the displayed settings.
   
9. Add a partner configuration to your SAML Configuration. The Name must be the identifier URL displayed by your IDP: 
   
10. Important: Do NOT specify a partner with Is Default until after you have tested and validated the SAML integration is working, including mapping of the admin role. Is Default will cause the basic Login buttons to use the designated SAML integration instead of Azure OIDC federation and will cause loss of access if incorrectly configured.
11. Choose a Display Name and Description for the partner. These will be displayed on the login page for the entity Id host.
    
    
12. Specify Sign-On and Logout URLs for your IdP. You may optionally specify an artifact resolution service URL. Select checkboxes for the desired signature settings (typically leave all signatures selected).
    
13. Add your partner certificate(s) with use Signature, by obtaining the base64 cer value of the certificate (e.g. by downloading partner metadata) and pasting the value into the certificate string field.
    
    If the certificate is well formed, other fields will be populated when you save and refresh.
    

Configuring Claims

In order to have an effective SAML integration you must configure the partner Identity Provider to give at minimum the following three kinds of claim value:

User Identifier: This should be a unique immutable ID such as an object id GUID, or objectSid

User Name: This should be a unique account name (such as userPrincipalName or sAMAccountName). A display name is possible, but less desirable.

Groups: The IdP should provide a listing of groups that may be mapped onto roles in Identity Panel. This does not have to include all groups possessed by the users, only those that will be used for permissions in Identity Panel Suite. Group claims may be provided as object ids, or as account names, but you will have to update security roles in Identity Panel accordingly. If federating using Azure AD as an underlying account store group object ids will require the fewest configuration changes.

Claim Setup

Having defined the claims on the Identity Provider, you must specify the URN claim type value for each required claim type (Id Claim, Login Name Claim, Groups Claim) in the Partner configuration. 

If you are unable to determine the claim URNs you may use the following procedure:

1. Leave the claim mappings blank or set to a known bad value
2. Using a separate or in-private browser session attempt to perform a SAML authentication
3. Use a web dashboard module to look for a Warning level output log entry. This will include all SAML claims on the login token for the failed request.

Updating Security Settings

Depending on your Identity Provider configuration you may need to specify additional or duplicate security roles. For example, if your group claims do not match Azure AD group object ids (hosted), or AD group object sids (on-premises).

When specifying groups for SAML claim based roles, the directory searchable by Identity Panel may be different from that used by your Identity Provider. In this scenario should exactly type or paste the expected claim value in the Security Principal field, then click on it or press <enter>