--- title: "Azure AD" url: "https://developer.tesma.com/integrations/integrations-azure" image: "https://developer.tesma.com/_og/d/c_Ocean.takumi,title_Azure+AD,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiM0Mjg1ZjQifX19,p_Ii9pbnRlZ3JhdGlvbnMvaW50ZWdyYXRpb25zLWF6dXJlIg,s_1tyauIa_JCSABZkS.png" --- # Azure AD (Entra ID) # Connect to your identity provider using Azure AD (Entra ID) If you use Azure AD to authenticate your users, integration with the CHG IdentityProvider is easy. Azure AD supports the SAML and OIDC protocol. Both are supported by the CHG IdentityProvider. ## [Connect via SAML](#connect-via-saml) To integrate your Azure AD via SAML protocol please read the [official documentation](https://learn.microsoft.com/en-us/entra/identity/saas-apps/tesma-tutorial) on the Microsoft website. ## [Overview using OIDC](#overview-using-oidc) > Following information is required to integrate your identity provider - Directory (tenant) Id - Application (client) Id - Client Id - Client secret The following steps will lead you through the process of configure a new application within your Azure AD. ## [Step 1 - Register new application](#step-1-register-new-application) Login to your [Azure Portal](https://portal.azure.com/) with administrative permissions. Open the App registrations service and add a new registration. ![New registration](https://developer.tesma.com/assets/images/integrations/federation/azuread-new.png) Provide a meaningful name like `CHG IdentityProvider`. If you already got a login redirect URL from our support please enter here. Proceeding the registration by hitting Register on the bottom. ![New application](https://developer.tesma.com/assets/images/integrations/federation/azuread-new-name.png) ## [Step 2 - Define login and logout URLs](#step-2-define-login-and-logout-urls) If no login redirect URL was set on the registration please add a platform first. Go to the Authentication tab and click on `Add a platform` and choose `Web`. Enter the login redirect URL and the logout URL which you got from our support. ![Define urls](https://developer.tesma.com/assets/images/integrations/federation/azuread-authentication-add.png) If you already provided a login redirect URL at the registration you only need to add the logout URL. This is optional if you don't want to support single sign-out. Go to the `Authentication` tab and enter the logout URL. ![Add logout url](https://developer.tesma.com/assets/images/integrations/federation/azuread-authentication.png) ## [Step 3 - Configure a secret](#step-3-configure-a-secret) Select the `Certificates & secrets` tab and add a new client secret. ![New client secret](https://developer.tesma.com/assets/images/integrations/federation/azuread-secret-new.png) Enter a description and choose an expiration. > Keep in mind, you must remember to assign a new secret in time or the users will not be able to log in. Remember the new generated secret on a safe place. ## [Step 4 - Provide information](#step-4-provide-information) Please provide the secret and the client and tenant ID to our support. This is the information required to configure the integration on our side. ![App registration details](https://developer.tesma.com/assets/images/integrations/federation/azuread-overview.png) ## [Additional attributes](#additional-attributes) To provide additional attributes on login such as group name or employee number, you have to configure these in the `Token configuration` tab. Please read the [documentation](https://go.microsoft.com/fwlink/?linkid=2108879) for further information. The optional claims should be in the ID token. ![Token configuration](https://developer.tesma.com/assets/images/integrations/federation/azuread-claims.png) - `sub` _required_ Contains the unique identifier for a user in the federated login provider. It is used to link CHG-MERIDIAN specific identity to the external IdentityProvider. Accepted alternatives: - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier` - `email` _required_ Contains the email address of the user. Accepted alternatives: - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` only if it contains a valid email - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier` only if it contains a valid email - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn` Contains the users prefered username. Fallback is the users email address if none is provided. Accepted alternatives: - `preferred_username` - `name` - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` - `given_name` Contains the users given name. Accepted alternatives: - `FirstName` - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` - `family_name` Contains the users family name. Accepted alternatives: - `LastName` - `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` - `nickname` Can be used as fallback for the name that is displayed for the user. It's only used if the name claim is empty and no first and last name can be found. - `generic other attributes` If the external identity provider sends other attributes than the ones mentioned above the CHG IdentityProvider will forward them to authenticated client applications but will not store them. Please keep those attributes to a minimum to avoid hitting limits of the used protocols such as header sizes or similar. Also this avoids distributing the users information to multiple systems unnecessarily. ## [Group information](#group-information) To provide group membership information of the user please read the [documentation](https://go.microsoft.com/fwlink/?linkid=2108880). Go to the `Token configuration` tab and add a new groups claim and select the groups types according to your needs. ![Add group claim](https://developer.tesma.com/assets/images/integrations/federation/azuread-groupsclaim.png) > In most scenarios only the ID of the group will be provided. See [documentation](https://docs.microsoft.com/en-us/azure/active-directory/hybrid/how-to-connect-fed-group-claims) for more information. CHG IdentityProvider can resolve the group name if required. To be able to resolve the group name please add the corresponding permission to the application. Go to `API permissions` and add the Microsoft Graph `GroupMember.Read.All` delegated permission. ![Add GroupMember.Read.All permission](https://developer.tesma.com/assets/images/integrations/federation/azuread-groups-permission.png) This permission _allows the app to list groups, read basic group properties and read membership of all groups the signed-in user has access to_. See [documentation](https://docs.microsoft.com/de-de/graph/permissions-reference#group-permissions) for more details. Please don't forget to grant admin consent for this permission. ![Grant admin consent](https://developer.tesma.com/assets/images/integrations/federation/azuread-grantadminconsent.png)