Single Sign-On (SSO) Settings
The following table lists the Single Sign-On (SSO) settings.
| Setting | Description | AD FS-specific | Azure AD-specific |
|---|---|---|---|
| Sign-In Protocol | The Sign-In Protocol for your system, either OAuth2, WS-Fed, or SAML2 | — | — |
| Server Address | The address of the identity provider, either a partial URL or an IP address/host name. | For AD FS, just the host name is sufficient. | For Azure AD, it is generally most convenient to enter your application’s sign-on endpoint without the protocol part of the URL, which should be saved for the next field, Endpoint URL Path. For example: https://login.microsoftonline.com/514a94b9-6a5b-4f0b-96aa-63dced118308 |
| Endpoint URL Path | The location on the identity provider's Web server that HMP should redirect unauthenticated browsers to in order to sign in. The Server Address and Endpoint URL Path are combined by HMP to get the full Web address of the sign-in endpoint. For OAuth2, the Endpoint URL Path should not include the authorize or token portions of the URL, as those are defined in the settings below. | If this is empty, HMP assumes that the default AD FS endpoint should be used for the chosen Sign-In Protocol.
| When using Azure AD, set this to the part of the sign-on endpoint that was omitted in the Server Address field.
|
| Sign-Out URL | If defined, when logging out of HMP, the user is redirected to this SSO logout page. | — | — |
| Relying Party Identifier | A URI that HMP passes to the identity provider that lets HMP select which configuration should be used to authenticate. | For AD FS, this value identifies the Relying Party Trust. On the Windows Server, this can be found under Administrative Tools in AD FS Management under AD FS → Trust Relationships → Relying Party Trusts. The value that should be configured will be in the "Identifier" column for whichever Relying Party Trust should be used. | For Azure AD, this value identifies the Application. On the AD Application's Configure tab, this is the App ID URI value under the Single Sign-On section. Note If the App ID URI value is not a valid URI, add a |
| Identity Metadata URL | When HMP’s authentication service starts, it loads the Token Signing Certificate automatically from the Identity Metadata URL. Single Sign-On configuration requires either the Identity Metadata URL or Token Signing Certificate field to be configured. If both are configured, HMP uses the specified Token Signing Certificate and ignores the Identity Metadata URL. If the Sign-In Protocol is WS-Fed or SAML2, the Identity Metadata URL should be the identity provider's Federation Metadata document. | For AD FS, an example value is: Tip You can check what Federation Metadata endpoint is currently set to on Windows Server's Administrative Tools > AD FS Management under AD FS > Service > Endpoints. | For Azure AD, an example Federation Metadata URL is: Tip You can find this by going to your Application on Azure AD and selecting View Endpoints on the bottom of the browser window. The URL is labeled "FEDERATION METADATA DOCUMENT". When the Sign-In Protocol is OAuth2, the Identity Metadata URL should be an OpenID Provider Metadata URL, which is currently available for Azure AD but not AD FS (as of 3.0). An example URL is: |
| UPN Claim Identity | Default value depends on selected protocol. This value may be modified to support a claim with another name or a standard property string. For example, if a custom field of
Tip If your SSO login fails, monitor calypso.log for a message such as "Provided UPN field is invalid" and enter the valid string into this field. | — | — |
| Token Signing Certificate | HMP needs to know the Token Signing Certificate used by the identity provider to verify that any tokens that it receives after a successful sign-in have not been tampered with. | When using AD FS with the Sign-In Protocol set to WS-Fed or SAML2, the Identity Metadata URL setting can be set to the AD FS Federation Metadata endpoint. In this case, the Token Signing Certificate is fetched automatically so this value does not need to be configured. For OAuth2, AD FS on Windows Server 2012 R2 does not currently have an OpenID Provider Metadata endpoint, so the Token Signing Certificate has to be configured. | With Azure AD, HMP fetches Token Signing Certificate automatically from the Identity Metadata URL, so this value does not need to be configured. However, if errors occur, the certificate may be exported from the application configuration in Azure (Base-64 format) and copied into this field. |
| Decryption Key | (SAML2 only) The Decryption Key is used to decrypt an encrypted assertion response after a successful sign-in. This setting is optional, as the assertion response may not be encrypted at all depending on the configuration of the identity provider. | With AD FS, the SAML2 assertion response can be encrypted by setting a certificate under Encryption settings for the Relying Party Trust that HMP uses. The Decryption Key should be the HMP private key associated with the certificate that was set. The WS-Fed token can also be encrypted, although HMP does not currently support decrypting it. | No decryption key is required when using SAML2 for Azure AD. |
| Client ID | (OAuth2 only) When using OAuth2, HMP must have a Client ID with an associated Redirect URI registered on the identity provider. If it does not, or the configured Redirect URI does not match the value that the Client ID was registered with, all Single Sign-On logins will fail. | With AD FS, you can see all of the Client IDs that are currently registered by running the Get-AdfsClient PowerShell cmdlet. The ClientId and RedirectUri fields of the correct client should be set as the values for the Client ID and Redirect URI fields on HMP. | The Client ID can be retrieved from Azure AD by navigating to the Configure tab for the OAuth2 Application and copying the value for Client ID under Properties. |
| Client Secret | (OAuth2 only) Client Secret is an optional key that HMP can use to get authorized by the identity provider to request access tokens for users. | No client secret is required when using OAuth2 for AD FS. | Client secrets are used by Azure AD. On Azure AD, Client Secrets are simply called keys and can be generated on the application's "Configure" page. Under keys, select a duration for the key to be valid, then click Save on the bottom of the browser window and copy the key value that appears. This is the Client Secret for the application. |
| Redirect URI | (OAuth2 only) This is the URL that the user should be taken to after authenticating using Single Sign-On. In general, this should be HMP’s SSO callback URL, which is https://calypso.local/sso/callback (replacing calypso.local with your HMP's real IP/host name). This field is not used for WS-Fed or SAML2 because the redirect is completely configured on the server side of the identity provider. | — | — |
| Token Endpoint | (OAuth2 only) Defines the token endpoint. Can be an absolute URL or relative to the server address+endpoint URL path. If not defined, and an OIDC metadata endpoint is configured in the Identity Metadata URL, HMP uses the token endpoint defined in the metadata response. If neither this field nor the Identity Metadata URL is defined, /token path is assumed. | — | — |
| Authorization Endpoint | (OAuth2 only) Defines the authorization endpoint. Can be an absolute URL or relative to the server address+endpoint URL path. If not defined, and an OIDC metadata endpoint is configured in the Identity Metadata URL, HMP uses the authorization endpoint defined in the metadata response. If neither this field nor the Identity Metadata URL is defined, /authorization path is assumed. | — | — |
| User Info Endpoint | (OAuth2 only) Defines the user info endpoint. Must be an absolute URL. If not defined, and an OIDC metadata endpoint is configured in the Identity Metadata URL, HMP uses the user info endpoint defined in the metadata response. | — | — |
