Identity Sources¶

Administration > Tenants > (Selected Tenant) > Identity Sources Administration > Users > Identity Sources

Overview¶

Morpheus can integrate with many of the most common identity source technologies, such as Active Directory, Okta, and many others. These can be configured via the Identity Sources button on any Tenant detail page (Administration > Tenants > Selected Tenant) or on the Users list page (Administration > Users). These integrations map roles within these sign-on tools to equivalent roles in Morpheus so at first log in users are assigned the appropriate role.

Active Directory¶

Overview¶

Active Directory is Microsoft’s primary authentication service widely used in Enterprise organizations and even via Microsoft’s cloud services. While Active Directory also supports LDAP protocol support (which Morpheus can integrate with as well), the main Active Directory integration can also be utilized. It is even possible to map Active Directory groups to equivalent Roles within Morpheus. Morpheus will connect over port 389 for non-secure LDAP and port 636 for secure LDAP.

Adding an Active Directory Integration¶

Navigate to Administration > Tenants
Select a Tenant
Select IDENTITY SOURCES
Select + IDENTITY SOURCE
Choose “Active Directory”
Populate the following:

Name
Unique name for authentication type.

AD Server
Hostname or IP address of AD Server.

Domain
Domain name of AD Domain.

Binding Username
Service account username for bind user.

Binding Password
Password for bind service account.

Required Group
The AD group users must be in to have access (optional)

Default Role
The default role a user is assigned if no group is listed under AD user that maps under Role Mappings section.

Service Account Holder
This is the admin account type in Morpheus and an AD group can be created and populated to a user that this role should be assigned. Roles are assigned dynamically based on group membership.

ENABLE ROLE MAPPING PERMISSION
When selected, Tenant users with appropriate rights to view and edit Roles will have the ability to set role mapping for the Identity Source integration. This allows the Tenant user to edit only the role mappings without viewing or potentially editing the Identity Source configuration.

MANUAL ROLE ASSIGNMENT
When selected, administrators can manually edit Roles for users created through this identity source integration from the user detail page (Administration > Users > Selected user).

Note

For more on Identity Source role mapping permissions, see the associated guide in our KnowledgeBase.

Select SAVE CHANGES.

Now allowed AD users can login to Morpheus via their Active Directory credentials and a User will be automatically generated to Morpheus with matching metadata and mapped Role permissions.

Note

Only the username is required with password, not the username@domain.

Note

Sub-tenant Morpheus API authentication for Active Directory generated users is not currently supported.

Azure Active Directory SSO (SAML)¶

Azure Active Directory Single Sign-on can be added as a Identity Source in Morpheus using the SAML Identity Source Type. The Azure AD SSO configuration is slightly different than other SAML providers, and this guide will assist in adding a Azure AD SSO Identity Source.

Create a Azure AD SAML Integration¶

Azure requires inputting the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) in the Azure SSO configuration before it provides the Endpoints and Certificate necessary to add the Integration into Morpheus. In order to get the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) to input into Azure SSO config, we need to create a base SAML Integration in Morpheus first.

To add a base SAML integration:

Navigate to Administration > Tenants
Select a tenant.
Select IDENTITY SOURCES in the Tenant detail page
Select + ADD IDENTITY SOURCE.
Select SAML SSO from the TYPE field
Add a Name, optional Description and any value in the LOGIN REDIRECT URL field.
Since we do not have the LOGIN REDIRECT URL from Azure yet, type any text such as test into the LOGIN REDIRECT URL field so the Identity Source Integration can be saved and the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) generated. We will edit the Integration with the proper LOGIN REDIRECT URL after configuring SSO in Azure.
Select SAVE CHANGES.

Upon save, the Entity ID (Identifier (Entity ID)) and SP ACS URL (Reply URL (Assertion Consumer Service URL)) will be provide in the Identity Source list view. Copy these for use in Azure SSO config.

Configure Azure SSO¶

This guide assumes an Azure AD Application has already been created in Azure with a subscription level high enough to configure SSO in the application. Please refer to Azure documentation if this has not already been configured.

Next, in the Azure Active Directory Application details page, select Single sign-on, then enter the following:
- Single Sign-on Mode dropdown
  Select SAML-based Sign-on
- Identifier (Entity ID)
  Enter the Entity ID URL from the Morpheus Identity Source Integration above.
- Reply URL (Assertion Consumer Service URL)
  Enter the SP ACS URL from the Morpheus Identity Source Integration above.
Save and click the Test SAML Settings button. Azure will confirm connection with Morpheus

In Azure’s User Attributes & Claims settings (step 2), select Add a group claim with value user.groups [SecurityGroup]

User Attributes & Claims config

**Required Claim**¶
Claim name	Value
Unique User Identifier (Name ID)	user.userprincipalname [nameid-format:emailAddress]

**Additional Claims**¶
Claim name	Value
http://schemas.microsoft.com/ws/2008/06/identity/claims/groups	user.groups [SecurityGroup]
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	user.mail
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	user.givenname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name	user.userprincipalname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	user.surname

Copy or keep available for reference the the Claim Names/Namespace URLs for entering Role Attribute Values in the Morpheus Identity Source Integration.
In Azure SSO config, if one has not been generated, select Create new certificate to generate a new SAML Signing Certificate.
Enter a valid email address to receive certificate expiration notifications (these are not Morpheus-generated email).
In Azure SSO config, select `Configure {AD App Name}

In the Configure sign-on pane, copy the following:

SAML Single Sign-On Service URL
This will be used for the LOGIN REDIRECT URL in the Morpheus Identity Source Integration settings
Sign-Out URL
This will be used for the LOGOUT REDIRECT URL in the Morpheus Identity Source Integration settings

Click on the SAML XML Metadata link, open the xml file, and copy the key between the <X509Certificate> and </X509Certificate>.

This will be used for the Public Key value in the SAML RESPONSE section of the Morpheus Identity Source Integration settings

Example Key (this key is an example and is not valid):

MIIC8ECCAdigAwIBAgIQEOZXlNx5wY9Dc6OwlsKEMzANBgkqhkiG9w0BAQsFADA0MTIwMAYDVQQDEylNaWNyb3NvZnQgQXp1cmUgRmVkZXJhdGVkIFNTTyBDZXJ0aWZpY2F0ZTAeFw0xODAyMTYxNTU4NTlaFw0yMTAyMTYxNTU4NTlaMDQxMjAwBgNVBAMTTU1pY3Jvc29mdCBBenVyZSBGZWRlcmF0ZWQgU1NPIENlcnRpZmljYXRlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2k/V6GcBpRkoxJd0DLbhubwd0kp65LD9IIh5PUY2ohBHvrFAy3SZ04mXoH7LWvY3oNrqxaNAksbYF6phOkONf/XeTdzor14xdGnTuD9zRqPsJHHisyfFBUG/CxYxzO6w9fAPzJGLzc0Y7o5lMW2OjINaqI4R/pqp3qw+nYf7DXSzY6tf1Sspk64jfZDt1jSVjD7upMItKPeOCRmeBUcnebjzwXqFBO7l4Vf5g1oEJvftT7Wpr4VVmoLh8rFGWbQ1wlmtsK9RrWTqdt3su2H9uNrEjWiZ62x6ate2fs0dXnz17KoV7RQOpqYtjom76jNUzorcl73D5AGwW6x+2wIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQCSjf2IOG6O3wdOmkfJ/pH6xzQVRz0GZQpol9ViQJJbJJqhLm4LjWT9VU2lYqdi0NdgtK7QthZo4J0ZFdUG6qfFTfPKqVn0AEHxiM4JWxfigzdMJUutHcRRoaJ8VvywZYJKE91e4TDuBOw8XqdBiBx627ZybXCuR/y56+ksYSRP87XdOcVvTftHYmQnDOf0qKrpgMK7LtmsEwqc7rKX7nTCenZnBEBOCFDBVH4QEzMrAznEPdJnQs9nJZBNCYJUrCRXbPKpXE9u8MlTVq4swFm96xsXkfeP8NFsgrXmzOn3BsHaBXqdhrrkbwq85VPWUaoIomlhAWQq/seC

Save the SSO config in Azure AD app and return to Morpheus

Edit the existing Azure AD SAML Integration¶

Now that we have the required information, we can finalize the Azure AD SAML Integration in Morpheus

Edit the existing Azure AD SAML Integration created in the first step and populate the following:

LOGIN REDIRECT URL
Add the SAML Single Sign-On Service URL copied from Azure SSO config.

LOGOUT REDIRECT URL
Add the Sign-Out URL copied from Azure SSO config.

SAML RESPONSE
Set to “Validate Assertion Signature”, then in the “Public Key” field enter the Public Key value we discussed in the last section

GIVEN NAME ATTRIBUTE NAME (May have to click “show” to see hidden SAML Assertion Attribute Names fields)
Enter the givenname Namespace url from Azure SSO config: http://schemas.xmlsoap.org/ws/2005/05/identity/claims

SURNAME ATTRIBUTE NAME
Enter the emailaddress Namespace url from Azure SSO config: http://schemas.xmlsoap.org/ws/2005/05/identity/claims

EMAIL ATTRIBUTE NAME (May need to scroll down within the SAML Assertion Attribute Names section see this field)
Enter the surname Namespace url from Azure SSO config: http://schemas.xmlsoap.org/ws/2005/05/identity/claims

Configure Role Mappings¶

Role mappings will map Azure AD Groups to Morpheus Roles. Azure AD users will be assigned Roles in Morpheus upon signing in based on their Group Membership in Azure AD.

Important

Use an Azure Groups Object ID, not Group name, when entering Role Mappings. Example: 7626a4a2-b388-4d9b-a228-72ce9a33bd4b

DEFAULT ROLE: Role a Azure AD user will be assigned by default upon signing in to Morpheus using this Identity Source.
REQUIRED AZURE AD GROUP OBJECT ID: Object ID of Azure AD Group a user must be a member of to be authorized to sign in to Morpheus. Users not belonging to this Group will not be authorized to login to Morpheus. This field is optional, and if left blank, any user from the Azure AD App will be able to sign in to Morpheus and will be assigned the Default Role if no Role Mappings match AD Group membership.
GROUP ASSERTION ATTRIBUTE NAME: Enter http://schemas.microsoft.com/ws/2008/06/identity/claims/groups for Azure AD SSO
Additional Role Mappings: The existing Roles in Morpheus will be listed. To map a Morpheus Role to an Azure AD Group, enter the Object ID of the desired Azure AD Group in the Role Attribute Value field for the corresponding Morpheus Role.

Important

Use an Azure Groups Object ID, not Group name, when entering Role Mappings. Example: 7626a4a2-b388-4d9b-a228-72ce9a33bd4b

ENABLE ROLE MAPPING PERMISSION: When selected, Tenant users with appropriate rights to view and edit Roles will have the ability to set role mapping for the Identity Source integration. This allows the Tenant user to edit only the role mappings without viewing or potentially editing the Identity Source configuration.
MANUAL ROLE ASSIGNMENT: When selected, administrators can manually edit Roles for users created through this identity source integration from the user detail page (Administration > Users > Selected user).

Note

For more on Identity Source role mapping permissions, see the associated guide in our KnowledgeBase.

Once populated, select SAVE CHANGES and the SAML identity source integration will be added. The Identity Source can be edited anytime to deactivate or change Role Mappings or other values.

Note

If Role mappings are edited after Azure AD SSO users have signed into Morpheus, currently logged in users will need to log out of Morpheus for the new Role mappings to take effect, when applicable.

Azure Group Lookups¶

When a user in azure ad has more that 150 group attributes, Azure does not include the group claims in the SAML response, and Morpheus is required to query Microsoft Graph to obtain the users group attribute values. When there are users that are members of more that 150 groups, populate the Azure Group Lookups section in order for those users to be able to use the Azure AD SAML SSO integration, otherwise no groups will be obtained and proper role mappings cannot occur.

AZURE TENANT ID: Add Azure AD Tenant ID if user group membership will exceed 150. See Copy Directory (tenant) and Application (client) IDs for information on obtaining an Azure AD Tenant ID
AZURE APP ID: Add Azure AD Application (Client) ID if user group membership will exceed 150. See Copy Directory (tenant) and Application (client) IDs for information on obtaining an Azure AD Application (Client) ID
AZURE APP SECRET: Add Azure Application (Client) Secret if user group membership will exceed 150. See Generate a Client Secret for information on creating an Azure Application (Client) Secret
ROLE LINK ATTRIBUTE NAME: default: http://schemas.microsoft.com/claims/groups.link. This is not normally changed.

Signing In to Morpheus¶

When there is an active SAML/Azure AD SSO Identity Source Integration, a new button will appear on the Morpheus login page with the name of the Identity Source Integration as the button title. Example: MORPHEUS SSO. Another button titled “USERNAME AND PASSWORD” is also added for Morpheus account authentication outside of an Identity Source.

SAML/Azure AD SSO users can log into Morpheus by clicking the SAML button
This will redirect the User to Azure AD app sign in url. If they are currently signed into Azure and authorized, the user will be instantly signed into Morpheus.
Local Morpheus users can select “USERNAME AND PASSWORD” to sign in with their local credentials as before.

Note

If no local users other than the System Admin have been created, “USERNAME AND PASSWORD” option will not be displayed, only the SAML option.

Okta¶

Overview¶

Morpheus allows users to integrate an Okta deployment for user management and authentication. In Morpheus, identity sources are added on a per-Tenant basis and Morpheus allows you to map Okta user groups to Morpheus user groups. User accounts are automatically created with matching metadata and role permissions when users are authenticated.

Adding an Okta Integration¶

Navigate to Administration > Tenants
Select a Tenant
Select IDENTITY SOURCES
Select + IDENTITY SOURCE
Choose TYPE: “Okta”
Populate the following, then select SAVE CHANGES:

Name: Unique name for authentication type
Description: A description for your new Okta Identity Source
Okta URL: Your Okta URL
Administrator API Token: Your Okta Administrator API Token
Required Group: The Okta group that users must be in to have access (optional)
Default Role: The default role a user is assigned if no group is listed under an Okta user that maps within the Morpheus Role Mappings section
ENABLE ROLE MAPPING PERMISSION: When selected, Tenant users with appropriate rights to view and edit Roles will have the ability to set role mapping for the Identity Source integration. This allows the Tenant user to edit only the role mappings without viewing or potentially editing the Identity Source configuration.
MANUAL ROLE ASSIGNMENT: When selected, administrators can manually edit Roles for users created through this identity source integration from the user detail page (Administration > Users > Selected user).

Note

For more on Identity Source role mapping permissions, see the associated guide in our KnowledgeBase.

Now, allowed Okta users can log into Morpheus via their Okta credentials and a user will be automatically generated within Morpheus with matching metadata and mapped Role permissions.

Note

If you’ve created multi-tenant roles, these will also appear here and can be mapped to Okta user groups allowing you to map users to equivalent user groups in Morpheus.

OneLogin¶

Adding OneLogin Identity Source Integration

Navigate to Administration > Tenants
Select the Tenant to add the Identity Source Integration
Select IDENTITY SOURCES
Select + IDENTITY SOURCE
Enter the following:

TYPE
OneLogin

NAME
Name of the Identity Source Integration in Morpheus

DESCRIPTION
Optional Description of the Identity Source

ONELOGIN SUBDOMAIN

example: morpheus-dev

Warning

Please verify the subdomain carefully. An invalid subdomain will cause authentication attempts by OneLogin users to fail.

ONELOGIN REGION
Specify US or EU region

API CLIENT SECRET
OneLogin API Client Secret from the Settings - API section in OneLogin portal

API CLIENT ID
OneLogin API Client ID from the Settings - API section in OneLogin portal

REQUIRED ROLE
Enter a role if OneLogin users logging into morpheus must have at least this OneLogin role to gain access to Morpheus.

DEFAULT ROLE
The default Morpheus Role applied to users created from OneLogin Integration if no other role mapping is specified below

ROLE MAPPINGS
Existing Morpheus Roles will be listed with fields to enter OneLogin Roles to map to. Users with OneLogin roles matching the role mappings will be assigned the appropriate Role(s) in Morpheus when signing in.

ENABLE ROLE MAPPING PERMISSION
When selected, Tenant users with appropriate rights to view and edit Roles will have the ability to set role mapping for the Identity Source integration. This allows the Tenant user to edit only the role mappings without viewing or potentially editing the Identity Source configuration.

MANUAL ROLE ASSIGNMENT
When selected, administrators can manually edit Roles for users created through this identity source integration from the user detail page (Administration > Users > Selected user).

Note

For more on Identity Source role mapping permissions, see the associated guide in our KnowledgeBase.

Select SAVE CHANGES and the OneLogin Integration will be added.

Users can now login to Morpheus with OneLogin credentials. The first Login will create a user in Morpheus matching the Username, email and Password from OneLogin. If a REQUIRED ROLE is specified in the Identity Source settings, only users with that Role in OneLogin will be able to login to Morpheus.

Important

OneLogin users will not authenticate in Morpheus if there is an existing Morpheus User with matching username or email address.

SAML Integration¶

Overview¶

The Morpheus SAML identity source integration allows customers to add user SSO to Morpheus, authenticated by external login SAML providers.

Adding a SAML Integration¶

To add a SAML integration:

Navigate to Administration > Tenants
Select a tenant.
Select IDENTITY SOURCES in the Tenant detail page
Select + ADD IDENTITY SOURCE.
Select SAML SSO from the TYPE field
Add a Name and optional Description for the SAML integration

There are 4 sections with fields that need to be populated depending on the desired configuration:

SAML Configuration
Role Mappings
Role Options
Assertion Attribute Mappings

SAML Configuration¶

LOGIN REDIRECT URL

This is the SAML endpoint Morpheus will redirect to when a user signs into Morpheus via SAML

SAML LOGOUT REDIRECT URL

The URL Morpheus will POST to when a SAML user logs out of Morpheus

INCLUDES SAML REQUEST PARAMETER

Yes (recommended) - the AuthN request will be sent via the ?SAMLRequest= parameter in the URL (GET)

No - the AuthN request will be submitted in the body of the request (POST)

Note

The SAML SP documentation should mention which binding to use but GET is most common

SAML REQUEST

No Signature - No signature is used on the SAML request

Self Signed - A self-signed X.509 Certificate is gentered after clicking SAVE CHANGES. This signature value can be used by the SAML SP to verify the authenticity of the request

Custom RSA Signature - Import a custom RSA Private Key and respective X.509 Certificate. This signature value can be used by the SAML SP to verify the authenticity of the request

SAML RESPONSE

Do Not Validate Assertion Signature - The SAML response signature from the SAML SP will not be validated

Validate Assertion Signature - The SAML reponse signature from the SAML SP will be validated. Enter the SAML SP X.509 certificate in the Public Key field

Role Mappings¶

DEFAULT ROLE: Role any SAML user will be assigned by default
ROLE ATTRIBUTE NAME: The name of the attribute/assertion field that will map to Morpheus roles, such a MemberOf
REQUIRED ROLE ATTRIBUTE VALUE: Attribute/assertion value that a user must be assigned/a member of to be authorized, such as group or role in the SAML SP. This is obtained from the attribute/assertion defined in the ROLE ATTRIBUTE NAME field
<Morpheus ROLE NAME>: Additional roles that can be mapped to a user, which will add to the DEFAULT ROLE. Attribute value that a user must be assigned/a member of to be authorized, such as group or role in the SAML SP. This is obtained from the attribute/assertion defined in the ROLE ATTRIBUTE NAME field

Note

For more on Identity Source role mapping permissions, see the associated guide in our KnowledgeBase.

Role Options¶

ENABLE ROLE MAPPING PERMISSION: When selected, Tenant users with appropriate rights to view and edit Roles will have the ability to set role mapping for the Identity Source integration. This allows the Tenant user to edit only the role mappings without viewing or potentially editing the Identity Source configuration.
MANUAL ROLE ASSIGNMENT: When selected, administrators can manually edit Roles for users created through this identity source integration from the user detail page (Administration > Users > Selected user).

Assertion Attribute Mappings¶

GIVEN NAME ATTRIBUTE NAME: SAML SP field value to map to Morpheus user First Name
SURNAME ATTRIBUTE NAME: SAML SP field value to map to Morpheus user Last Name
EMAIL ATTRIBUTE: SAML SP field value to map to Morpheus user email address

Once populated, select SAVE CHANGES and the SAML identity source integration will be added.

In the Identity Sources section, important information for configuration of the SAML integration is provided. Use the SP ENTITY ID and SP ACS URL for configuration on the external login SAML provider side.

Note

In some cases, the SAML provider may need these values before providing the LOGIN REDIRECT URL and other values. When creating the integration, the NAME and LOGIN REDIRECT URL can contain any values, then selecting SAVE CHANGES will generate the above values. The NAME and LOGIN REDIRECT URL can be edited later, once the SAML configuration is created in the SAML provider.

ENTITY ID
SP ACS URL
LOGIN REDIRECT URL
SP METADATA

Sample Metadata code output:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><EntityDescriptor entityID="https://someip.com/saml/eDKL60P25" xmlns="urn:oasis:names:tc:SAML:2.0:metadata"><SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"><NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</NameIDFormat><AssertionConsumerService index="0" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://someip.com/externalLogin/callback/eDKL60P25"/></SPSSODescriptor></EntityDescriptor>

Note

Different SAML providers will have different field names and requirements. An Okta SAML Dev environment was used for the example integration in this article.

Okta SAML SSO¶

For Okta SAML integration, the following fields are mapped:

LOGIN REDIRECT URL : Identity Provider Single Sign-On URL
ENTITY ID: Audience URI (SP Entity ID)
SP ACS URL: Single sign on URL

Onelogin SAML SSO¶

For Onelogin SAML integration, the following fields are mapped:

LOGIN REDIRECT URL : SAML 2.0 Endpoint (HTTP)
SAML LOGOUT REDIRECT URL : SLO Endpoint (HTTP)
SIGNING PUBLIC KEY : X.509 Certificate
ENTITY ID: ACS (Consumer) URL Validator
SP ACS URL: ACS (Consumer) URL