# Azure Active Directory SSO (SAML)

Azure Active Directory Single Sign-on can be added as a Identity Source in HPE Morpheus Enterprise 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 Azure Enterprise Application

### Procedure

1. Login to the [Azure Portal](https://portal.azure.com)
2. Navigate to: Azure Active Directory  >  Enterprise Applications
3. Click the `+ New application` button at the top
4. Click the `+ Create your own application` button at the top
5. Ensure `Integrate any other application you don't find in the gallery (Non-gallery)` is selected and enter a name for the app. Common examples are: `MorpheusSSO`
6. Click the `Create` button at the bottom and wait for it to complete
7. Once created, you’ll be in the `Overview` of the application created. Navigate to the `Single sign-on` section from the left pane
8. Choose `SAML` as the Single sign-on method
9. Copy both the `Login URL` and `Logout URL` in Step 4, we’ll need these in some of the next steps
10. Before we can continue configuring the application, the configuration needs to be generated in HPE Morpheus Enterprise for more data

## Create an Azure AD SAML Integration in HPE Morpheus Enterprise

### About this task

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 HPE Morpheus Enterprise. In order to get the `Identifier (Entity ID)` and `Reply URL (Assertion Consumer Service URL)` to input into Azure SSO configuration, we need to create a `Azure AD SAML SSO` integration in HPE Morpheus Enterprise first.

To add the integration:

### Procedure

1. Login to HPE Morpheus Enterprise
2. Navigate to Administration > Tenants
3. Click a tenant hyperlink
4. Click the IDENTITY SOURCES button in the Tenant detail page
5. Click the + ADD IDENTITY SOURCE button
6. Select `Azure AD SAML SSO` from the `TYPE` dropdown
7. Add 

   - Name
   - (Optional) Description
   - Paste the `Login URL` copied from Azure into the `LOGIN REDIRECT URL` field
   - Paste the `Logout URL` copied from Azure into the `SAML LOGOUT REDIRECT URL` field
8. This is the minimum information needed for now, which will let us generate the details needed from HPE Morpheus Enterprise. We’ll return to this configuration page later to enter more information.
9. Click the SAVE CHANGES button 

   IMPORTANT

   Setting SAML REQUEST to “No Signature” and SAML RESPONSE to “Do Not Validate Assertion Signature” is allowed but not recommended for security reasons.

   Upon saving, 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 configuration.

   ![../../_images/saml_setup.png](https://support.hpe.com/hpesc/public/api/document/sd00007621en_us/GUID-C3ECE586-166D-49EB-85B2-42D73E125E79-high.png)

## Configure Azure Enterprise Application

### About this task

This guide assumes an Azure AD Enterprise Application has already been created. Please refer to documentation above, if this has not already been configured.

### Procedure

1. Navigate to: Azure Active Directory  >  Enterprise Applications  >  Single sign-on
2. Choose `SAML` as the Single sign-on method
3. On Step 1 (`Basic SAML Configuration`), click the `Edit` button and enter the following: 

   - Identifier (Entity ID)
     :   Enter the `Entity ID` URL from the HPE Morpheus Enterprise Identity Source Integration above
   - Reply URL (Assertion Consumer Service URL)
     :   Enter the `SP ACS URL` from the HPE Morpheus Enterprise Identity Source Integration above
   - Logout URL
     :   Enter the following format: `https://yourUrl/login/` If this is a sub tenant, the format may instead be the following: `https://yourUrl/login/account/1` The login URL can be found under IDENTITY SOURCES in the tenant
4. On Step 2 (`Attributes and Claims`), click the `Edit` button
5. Click the `Add a group claim` button at the top
6. Choose `All groups` and ensure `Group ID` is selected for the `Source attribute` dropdown 

   NOTE

   You can also choose `Security groups`, which ever makes more sense for the organization
7. Close the pane and return to the Enterprise Application in the `Single sign-on` section
8. On Step 3 (`SAML Certificates`), click the `Download` link next to `Certificate (Base64)` and `Federation Metadata XML` 

   NOTE

   The files will download, keep them available for later configuation in HPE Morpheus Enterprise
9. Navigate to `Users and Groups` in the left pane
10. Click the `Add user/group` button
11. Add Azure groups to this application that will be able to login to HPE Morpheus Enterprise 

    NOTE

    the object ID for each of these groups, as they will be used later when configuring HPE Morpheus Enterprise to map the group to roles
12. Once groups have been added, click the `Assign` button at the bottom

## Configure the Azure AD SAML Integration in HPE Morpheus Enterprise

### Procedure

1. Login to HPE Morpheus Enterprise using `Username and Password`, as usual
2. Navigate to Administration > Tenants
3. Click a tenant hyperlink
4. Select IDENTITY SOURCES in the Tenant detail page
5. Click the pencil (edit) next to the integration created previously
6. Ensure the `SAML REQUEST` field is set to `Self Signed` 

   NOTE

   A custom RSA signature can be used here if needed, if required by the orgnaization
7. Ensure the `SAML RESPONSE` field is set to `Validate Assertion Signature` 

   NOTE

   With this setting, if the assertion signature ever changes in the Azure Enterprise Application, this would need to be updated to match
8. Edit/view the downloaded `Federation Metadata XML` (`.xml` extension) file from the previous section 

   NOTE

   It is recommended to use `Microsoft Edge`, or another browser, to view the contents
9. In the `Federation Metadata XML` file, locate the `<X509Certificate> </X509Certificate>` under the `<Signature>` section. Copy the entire contents between the `<X509Certificate>` and `</X509Certificate>`, it is very long
10. Paste the value copied from the `Federation Metadata XML` file into the `Public Key (Optional)` box, below the `SAML RESPONSE` dropdown

## Configure Role Mappings

### About this task

Role mappings will map Azure AD Groups to Morpheus Roles. Azure AD users will be assigned Roles in HPE Morpheus Enterprise 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 HPE Morpheus Enterprise 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 HPE Morpheus Enterprise. Users not belonging to this Group will not be authorized to login to HPE Morpheus Enterprise. This field is optional, and if left blank, any user from the Azure AD App will be able to sign in to HPE Morpheus Enterprise 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 HPE Morpheus Enterprise will be listed. To map a HPE Morpheus Enterprise 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 HPE Morpheus Enterprise 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](https://support.morpheusdata.com/s/article/How-to-enable-Subtenant-admins-to-edit-Identity-Source-role-mapping?language=en_US) 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 HPE Morpheus Enterprise, currently logged in users will need to log out of HPE Morpheus Enterprise for the new Role mappings to take effect, when applicable.

### Procedure

1. Under the `Role Azure Group Mappings` secton, verify the `DEFAULT ROLE` dropdown has the role in HPE Morpheus Enterprise selected that all users will be assigned by default 

   - It is recommended that this role contains no permissions, which ensures that anyone who authenticates gets no access
2. Under the `Role Azure Group Mappings` secton, you will see role names listed. Next to these are text boxes with `Assertion Attribute Mappings` inside. Enter group object IDs from Azure into these text boxes. This will map the Azure AD groups to specific roles in Morpheus
3. Finally, click `Save Changes` at the bottom of the page 

   Here is an example of the configuration above:

   ![../../_images/saml_setup_complete.png](https://support.hpe.com/hpesc/public/api/document/sd00007621en_us/GUID-5666456C-8FE1-4305-816E-FD051CC4636F-high.png)

## 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 HPE Morpheus Enterprise 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](https://support.hpe.com/hpesc/public/api/document/sd00007621en_us/render?page=GUID-76D48C9A-CE72-4BB0-B725-DBD8A9469FFB.html#GUID-9FD4BFE9-1725-42FF-8EFE-5F297A4D152D) 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](https://support.hpe.com/hpesc/public/api/document/sd00007621en_us/render?page=GUID-76D48C9A-CE72-4BB0-B725-DBD8A9469FFB.html#GUID-9FD4BFE9-1725-42FF-8EFE-5F297A4D152D) 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](https://support.hpe.com/hpesc/public/api/document/sd00007621en_us/render?page=GUID-76D48C9A-CE72-4BB0-B725-DBD8A9469FFB.html#GUID-0A7984C3-E094-45D6-B2D9-ED3179A79988) 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.

## Logging Into HPE Morpheus Enterprise with Azure AD SAML

### Procedure

1. Navigate to the HPE Morpheus Enterprise URL
2. A new button will appear to allow sign-in using Azure AD SAML, with the same name as the integration. Click the button 

   ![../../_images/sign_in_page.png](https://support.hpe.com/hpesc/public/api/document/sd00007621en_us/GUID-1FEC124E-FF68-4E72-9872-1D336777E8E5-high.png)
3. Sign-in with your Microsoft/Azure account 

   ![../../_images/ms_signin.png](https://support.hpe.com/hpesc/public/api/document/sd00007621en_us/GUID-BF8B57F9-055B-4A8C-AEB5-95ABA09BD3DF-high.png)

   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.
