--- title: Register a custom or SSO application description: The topics in this section are for tenants created on or after January 12, 2023. Learn more in Application management migration FAQ. component: pingoneaic page_id: pingoneaic:app-management:register-a-custom-application canonical_url: https://docs.pingidentity.com/pingoneaic/app-management/register-a-custom-application.html keywords: ["Application Management", "Setup & Configuration"] section_ids: register_a_custom_application_or_service: Register a custom application or service openid-connect-oidc: OpenID Connect (OIDC) oauth2-set-up-single-sign-on: OAuth 2.0 - Set up single sign-on custom-saml-app-template-sso: SAML 2.0 custom-saml-app-setup-sso: SAML 2.0 - Set up single sign-on bookmark: Bookmark register-SSO-application: Register an SSO application sso-microsoft-365: Microsoft 365 sso-microsoft-365-requirements: Microsoft 365 requirements config-ms-365: Configure the Microsoft 365 application sso-microsoft-365-hybrid-join-requirements: Microsoft Entra hybrid join requirements ws-trust-config: Configure WS-Trust microsoft_365_update_sso_settings: Microsoft 365 update SSO settings sso-microsoft-365-settings: Microsoft 365 Sign On settings sso-manage-ms-365-cert: Manage Microsoft 365 application signing certificates view_and_download_the_signing_certificate: View and download the signing certificate rotate_the_signing_certificate: Rotate the signing certificate sso-manage-ms-365-x509-certs: Manage Microsoft 365 application trusted certificates view_trusted_certificate_details: View trusted certificate details add_a_trusted_certificate: Add a trusted certificate delete_a_trusted_certificate: Delete a trusted certificate sso-custom-wsfed: Custom WS-Fed sso-custom-wsfed-requirements: Custom WS-Fed requirements sso-config-custom-wsfed-app: Configure the custom WS-Fed application sso-custom-wsfed-settings: Custom WS-Fed Sign On settings sso-manage-custom-wsfed-cert: Manage the custom WS-Fed application signing certificate sso-view-download-custom-wsfed-cert: View and download the signing certificate sso-rotate-custom-wsfed-cert: Rotate the signing certificate next_step: Next step --- # Register a custom or SSO application | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The topics in this section are for tenants created on or after January 12, 2023. Learn more in [Application management migration FAQ](../product-information/migration-dependent-features/application-management-migration-faq.html). | If you can't find a template for your OpenID Connect (OIDC) or SAML applications, Advanced Identity Cloud lets you create custom applications, where you supply all the configuration information. | | | | - | ------------------------------------------------------------------------------ | | | Provisioning is not available for custom or single sign-on (SSO) applications. | ## Register a custom application or service Learn more about OpenID Connect (OIDC) applications in [Application management](applications.html). 1. On the Advanced Identity Cloud admin console, go to Applications, and click + Custom Application. 2. In the Add a Custom Application modal, choose one of the following: * OIDC - OpenID Connect * SAML * Bookmark * WS-Fed Learn more in [Custom WS-Fed](#sso-custom-wsfed). 3. Click Next. 4. Complete application setup in one of the following applicable subsections. ### OpenID Connect (OIDC) 1. Choose the application type you want to register. Learn more in [OIDC applications](applications.html#oidc_openid_connect_applications). * Native / SPA * Web * Service 2. Click Next. 3. In the Application Details modal, configure the following fields: * Name: The name of the application. * Description: A description of the application. * Application Owners: The owners of the application. * App Logo URI: The URL of the application logo. 4. Click Next. 5. In the Service Settings modal, configure the following fields: 1. Enter a Client ID to display in the applications list, and if shown, enter a Client Secret. Remember the client secret. If you forget the client secret, you must reset it on the Sign On tab on the edit application page. 2. Enable Use Secret Store for secrets to display the Secret Label Identifier field. Learn how to configure the Secret Label Identifier field in [General Settings](#oauth2-general-settings). 6. Click Create Application. #### OAuth 2.0 - Set up single sign-on 1. On the Sign On tab, set or review the following credentials: > **Collapse: Client Credentials** > > | Field | Description | > | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | Client ID | Identifier used to register your client application with Advanced Identity Cloud, and when your application authenticates to Advanced Identity Cloud. | > | (Web and Service) Client Secret | Password used to register your client application with Advanced Identity Cloud, and when your application authenticates to Advanced Identity Cloud. | > | Discovery URI | The URI where the application retrieves the OpenID Provider information for this realm.Default: `https:///am/oauth2/realm-name/.well-known/openid-configuration` | > **Collapse: Show advanced settings** > > | Field | Description | > | -------------------------------- | ------------------------------------------------------------------------------------ | > | OAuth2.0 Authenticate Endpoint | The endpoint for OAuth2.0 authentication. | > | OAuth2.0 Authorization Endpoint | The endpoint for OAuth2.0 authorization. | > | OAuth2.0 Token Endpoint | The endpoint the application uses to get an access token or a refresh token. | > | OAuth2.0 Introspect Endpoint | The endpoint that returns validation information for identifier-based access tokens. | > | OAuth2.0 Userinfo Endpoint | The endpoint that returns information about an end user. | > | OAuth2.0 Identity Token Endpoint | The endpoint that returns the identity token. | > **Collapse: General Settings** > > | Field | Description | > | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | > | Sign-in URLs | Custom URL for handling login. Overrides the default login page. | > | Sign-out URLs | Custom URL for handling logout. Example: https\://client.example.com:8443/am/XUI/?realm=/#logout. | > | Grant Types | Specify the set of OAuth 2.0 grant types, also known as grant flows, allowed for this client: | > | Scopes | Specify scopes presented to the resource owner when the resource owner is asked to authorize client access to protected resources. The `openid` scope is required. | > | Use Secret Store for secrets | Enable to display the Secret Label Identifier field. | > | Secret Label Identifier | Enter a value that represents the `` part of a secret label for an OAuth 2.0 client. Advanced Identity Cloud uses the identifier to generate secret labels in the following format:- Client Secret Identifier > > `am.applications.oauth2.client..secret` > > - Client JWT Bearer Public Key Identifier > > `am.applications.oauth2.client..jwt.public.key` > > - Client ID Token Public Encryption Key Identifier > > `am.applications.oauth2.client..id.token.enc.public.key` > > - mTLS Self-signed Certificate Identifier > > `am.applications.oauth2.client..mtls.trusted.cert`Learn more in [Secret labels](../tenants/esvs-signing-encryption.html#secret-labels). | 2. Review Advanced Settings: > **Collapse: Access** > > | Field | Description | > | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | Default Scopes | Scopes set automatically when tokens are issued. The `openid` scope is required. | > | Response Types | The response types that the client uses. The response type value specifies the flow that determines how the ID token and access token are returned to the client. By default, the following response types are available:- `code`. Specifies that the client application requests an authorization code grant. > > - `token`. Specifies that the client application requests an implicit grant type and requests a token from the API. > > - `id_token`. Specifies that the client application requests an ID token. > > - `code token`. Specifies that the client application requests an access token, access token type, and an authorization code. > > - `token id_token`. Specifies that the client application requests an access token, access token type, and an ID token. > > - `code id_token`. Specifies that the client application requests an authorization code and an ID token. > > - `code token id_token`. Specifies that the client application requests an authorization code, access token, access token type, and an ID token. | > | Claims | Claims can be entered as simple strings, such as `name`, `email`, `profile`, or `sub`. Or, as a pipe-separated string in the format: `scope\|locale\|localized description`. For example, `name\|en\|Full name of end user`. | > | Allow wildcard ports in redirect URLs | Whether Advanced Identity Cloud allows wildcards (`*` characters) in the redirection URI port to match one or more ports.The URL configured in the redirection URI must be either localhost, 127.0.01, or ::1. For example, http\://localhost:\*/, https\://127.0.0.1:80\*/, or \https\://\[::1]:\*443/.Enable this setting, for example, for desktop applications that start a web server on a random free port during the OAuth 2.0 flow. | > **Collapse: Authentication** > > | Field | Description | > | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | Token Endpoint Authentication Method | The method that the client uses to authenticate to Advanced Identity Cloud. Choose one:- `client_secret_basic`. Clients authenticate using the HTTP Basic authentication scheme after receiving a client\_secret value. > > - `client_secret_post`. Clients authenticate by including the client credentials in the request body after receiving a client\_secret value. > > - `private_key_jwt`. Clients sign a JSON web token (JWT) with a registered public key. | > | Client Type | * Confidential clients can maintain the confidentiality of their credentials. For example, a web application runs on a server where its credentials are protected. > > * Public clients run the risk of exposing their passwords to a host or user agent. For example, a JavaScript client running in a browser may be accessible to the public at large. | > | Implied Consent | When enabled, the resource owner will not be asked for consent during authorization flows. The OAuth2.0 Provider must also be configured to allow clients to skip consent. | > | OAuth 2.0 Mix-Up Mitigation active | Enable this setting only if this OAuth 2.0 client supports the [OAuth 2.0 Mix-Up Mitigation draft](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-mix-up-mitigation-01), otherwise Advanced Identity Cloud won't validate access token requests received from this client. | > | Default ACR values | Default Authentication Context Class Reference values. Specify strings that will be requested as Voluntary Claims by default in all incoming requests. | > | Request URIs | Specify request\_uri values that a dynamic client pre-registers. | > | Client JWT Bearer Public Key | A base64-encoded X509 certificate in PEM format used to obtain the client's JWT bearer public key. The client uses the private key to sign client authentication and access token request JWTs. Advanced Identity Cloud uses the public key for verification. | > | Subject Type | Default value is public.* Choose pairwise if you want each client to receive a different subject value. This prevents correlation between clients. > > * Choose public if you want each client to receive the same subject value. | > | Default Max Age | Enable this option to enforce a default maximum age of 10 minutes. If the end user session is not currently active, and if more than 10 minutes have passed since the end user last authenticated, then the end user must authenticate again. | > | Use Certificate-Bound Access Tokens | Enable this option if you want access tokens issued to this client to be bound to an X.509 certificate. When enabled, access tokens will use the X.509 certificate to authenticate to the `access_token` endpoint. | > **Collapse: Token Lifetimes** > > | Field | Description | > | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | Authorization code lifetime (seconds) | The time an authorization code is valid for. Default value: 120 | > | Access token lifetime (seconds) | The time an access token is valid for, in seconds If you set the value to 0, the access token will not be valid. A maximum lifetime of 600 seconds is recommended. Default value: 3600 | > | Refresh token lifetime (seconds) | The time a refresh token is valid for. If this field is set to -1, the refresh token will never expire. Default value: 604800 | > | JWT token lifetime (seconds) | The amount of time the JWT is valid for. Default value: 3600 | > **Collapse: Consent Screen** > > | Field | Description | > | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | > | Display Name | Custom user-facing title. In this example, MyClient. | > | Display Description | User-facing instruction text. In this example, "This application is requesting the following information:" | > | Privacy Policy URI | URI containing the client's privacy policy documentation. The URI is displayed as a link in the consent page.![200](../realms/_images/consent-screen.png) | > **Collapse: Client Management** > > | Field | Description | > | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | > | Access Token | Specify the `registration_access_token` value you provided when registering the client, and then subsequently, when reading or updating the client profile. | > **Collapse: Session Management** > > | Field | Description | > | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | Client Session URI | Specify the relying party (client) URI to which the OpenID Connect Provider sends "session changed" notification. Message is sent using the HTML 5 postMessage API. | > **Collapse: Endpoint Response Formats** > > | Field | Description | > | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | User info response format | Specify the output format from the `userinfo` endpoint. The supported output formats are:- (default) User info JSON response format. > > - User info encrypted JWT response format. > > - User info signed JWT response format. > > - User info signed then encrypted response format. | > | Token Introspection Response Format | Specifies the format of the token introspection response. The possible values for this property are:- JSON response format > > - Signed JWT response format > > - Signed then encrypted JWT response format | > **Collapse: Signing and Encryption** > > | Field | Description | > | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | > | Public key selector | Select the public key for this client, which comes from the JWKs\_URI, manual JWKs, or X.509 field. | > | JSON Web Key URI | The URI that contains the client public keys in JSON web key format. | > | JSON Web Key | Raw JSON web key value containing the client public keys. | > | ID Token Encryption Public Key | The RSA public key for encrypting ID tokens in X.509 PEM format. For example:+```none > -----BEGIN PUBLIC KEY----- > ...... > -----END PUBLIC KEY----- > ``` | > | Enable ID Token Encryption | When enabled, encryption uses the algorithm that the ID token must be encrypted with. Default algorithm value is RSA1\_5 (RSAES-PKCS1-V1\_5). | 3. Click Save. ### SAML 2.0 1. On the Application Details page, configure the following fields: * Name: The name of the application. * Description: A description of the application. * Application Owners: The owners of the application. * App Logo URI: The URl of the location of the application logo. 2. Click Create Application. #### SAML 2.0 - Set up single sign-on 1. Click the Sign On tab. 2. Click Set Up SSO. 3. If you have set up multiple domains, in the Select a domain drop-down field, select a domain to use for sign-on. 4. Click Next. 5. Follow the steps on the Set Up Single Sign-on page. 6. Click Next. 7. Click Save. 8. To view IdP metadata for the application, click View IdP Metadata. 9. To update the application provider metadata, click Update Metadata. 10. To download a certificate, click Download Certificate. 11. Review or copy the following credentials: > **Collapse: Endpoints** > > | Field | Description | > | ---------------------------- | ---------------------------------------- | > | IDP-Initiated Login Endpoint | The login endpoint initiated by the IDP. | 12. Review or edit the following: > **Collapse: Settings** > > | Field | Description | > | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | Single Sign On URL | The location where the SAML assertion is sent with an HTTP POST. This is often referred to as the SAML Assertion Consumer Service (ACS) URL for your application. | > | Audience URI (SP Entity ID) | The application-defined unique identifier that is the intended audience of the SAML assertion. This is most often the SP Entity ID of your application. | > | Response | Signed or Unsigned. | > | Assertion Signature | Signed or Unsigned. | > | Use a journey to authenticate users to this application | Enable to display a drop-down list of journeys. Select a journey to be used in the authentication step of the SAML 2.0 federation flow. From the list of journeys, you can also perform the following actions:- Click the add icon ([icon: add, set=material, size=inline]) to create a new journey. > > - Click the edit icon ([icon: edit, set=material, size=inline]) to edit a journey.These actions open a journey editor.Learn more about SAML 2.0 app journeys in [Configure a SAML 2.0 application journey](../am-saml2/configure-providers.html#samlapp-journey). | 13. To set advanced settings, click Show advanced settings, and set or review the following: | Field | Description | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Name ID Format | Identifies the SAML processing rules and constraints for the assertion's subject statement. Use the default value of `Unspecified` unless the application explicitly requires a specific format. | | Application Username | Determines the default value for a user's application username. The application username is used for the assertion's subject statement. Select from one of the following options:- Username - Email - Custom: Allows you to specify a script that provides the application username. Scroll to select or edit an existing script, or click the plus sign to add a new [NameID mapper](../am-saml2/custom-nameid-mapper.html) script. | | Assertion Encryption | Encrypted or Unencrypted. | | Single Logout | Enable to allow the application to initiate Single Logout. Then in the Single Logout URL field, enter the location where the logout response is sent. | | Attribute Statements (optional) | Insert statements into the SAML assertions shared with your application. Set the Name, Name Format, and Value for each statement. Click the plus sign to add a new statement. | 14. Click Save. ### Bookmark You can now register a bookmark application, such as OneNote, Evernote, Google Bookmarks, or raindrop.io, to direct users to specific URLs. A bookmark application displays shortcut links on dashboards. When you click one of the links, the browser opens a new tab. 1. On the Application Details page, configure the following fields: * Name: The name of the application. * Description: A description of the application. * Application Owners: The owners of the application. * URL: The sign-in URL for the application. * App Logo URI: The URl of the location of the application logo. 2. Click Create Application. ## Register an SSO application You can configure your target application for SSO without provisioning. ### Microsoft 365 | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | The Microsoft 365 application requires WS-Federation/WS-Trust, which is an [add-on capability](../product-information/add-on-capabilities.html). Contact your Ping Identity representative to add this to your PingOne Advanced Identity Cloud subscription. | The Microsoft 365 application lets you set up SSO for web-based access, rich client applications, and Microsoft Entra hybrid joined devices: * For web-based access, it uses the [WS-Federation](https://en.wikipedia.org/wiki/WS-Federation) identity protocol and the [Passive Requestor Profile](https://en.wikipedia.org/wiki/WS-Federation_Passive_Requestor_Profile) (where the passive requestor is an end user's browser). Advanced Identity Cloud acts as the Identity Provider (IdP) and Microsoft 365 acts as the Service Provider (SP). When an end user tries to access a protected resource, such as `office.com`, the SP redirects them to the IdP to authenticate. The user signs on with their Advanced Identity Cloud credentials. After successful authentication, Advanced Identity Cloud generates a token and then redirects the user back to the SP with the token. The SP validates the token and grants the user access to the protected resource. * For rich client applications, such as Microsoft Outlook or SharePoint, it uses the WS-Trust protocol to issue security tokens. Learn more in [Configure WS-Trust](#ws-trust-config). * For Microsoft Entra hybrid joined devices, it uses the WS-Trust protocol to support SSO. A hybrid joined device is joined to an on-premises Active Directory (AD) and Microsoft Entra ID. Advanced Identity Cloud acts as the federated IdP for Entra ID. When a user signs on to a hybrid joined device, Windows authenticates the user against the on-premises AD. For access to cloud resources, Entra ID redirects the authentication request to Advanced Identity Cloud. After successful authentication, Advanced Identity Cloud issues a security token that Entra ID uses to issue a Primary Refresh Token (PRT) to the device, which enables SSO to Entra ID applications. Learn more in [Microsoft Entra hybrid join requirements](#sso-microsoft-365-hybrid-join-requirements). #### Microsoft 365 requirements 1. Enable WS-Federation [add-on capability](../product-information/add-on-capabilities.html). 2. [Add a verified domain in Entra ID](https://learn.microsoft.com/en-us/entra/identity/users/domains-manage). 3. To use provisioning with Microsoft 365, create an Advanced Identity Cloud Entra or Active Directory provisioning application with matching: * Email address style identifier. For example, mapping `userName` > `userPrincipalName` (UPN). * Unique ID. For example, mapping `_id` > `objectGUID`. * [Apply a transformation script](provision-an-application.html#apply-a-transformation-script-to-a-mapping) to Base64-encode the `objectGUID`. > **Collapse: Show example transformation script** > > ```javascript > /* > Convert objectGUID in string format to Base64 format. > 1. Convert objectGUID to hex > 2. Reverse the byte order of the first three components of objectGUID > 3. Base64 encode > */ > var uuid = Packages.java.util.UUID.fromString(source); > > var buffer = Packages.java.nio.ByteBuffer.allocate(16); > buffer.putLong(uuid.getMostSignificantBits()); > buffer.putLong(uuid.getLeastSignificantBits()); > > var uuidBytes = buffer.array(); > var guidBytes = Packages.java.util.Arrays.copyOf(uuidBytes, uuidBytes.length); > > guidBytes[0] = uuidBytes[3]; > guidBytes[1] = uuidBytes[2]; > guidBytes[2] = uuidBytes[1]; > guidBytes[3] = uuidBytes[0]; > guidBytes[4] = uuidBytes[5]; > guidBytes[5] = uuidBytes[4]; > guidBytes[6] = uuidBytes[7]; > guidBytes[7] = uuidBytes[6]; > > var encoder = Packages.java.util.Base64.getEncoder(); > encoder.encodeToString(guidBytes); > ``` 4. Create a journey with authenticated user attributes required for WS-Fed response message. You can use a scripted decision node for this. > **Collapse: Show example journey** > > ![Example journey for Microsoft 365 SSO](_images/ui-applications-ms365-sso-example-journey.png) > **Collapse: Show example for scripted decision node** > > ```javascript > /* > - Data made available by nodes that have already executed are available in the sharedState variable. > - The script should set outcome to either "true" or "false". > - Note: This script is not fault-tolerant. It is simply meant to give an idea how script nodes may be used in the context of the webinar. > */ > var fr = JavaImporter(org.forgerock.openam.auth.node.api.Action); > > // get the user id from the node state. > var userId = nodeState.get("_id").asString(); > > // get the username from the user repository. > var username = idRepository.getAttribute(userId, "uid").iterator().next(); > > // add user id and username to the session property. > action = fr.Action.goTo("true") > .putSessionProperty("am.protected.immutableID", userId) > .putSessionProperty("am.protected.userPrincipalName", username) > .build(); > > outcome = "true"; > ``` | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For a list of AM attribute names you can use in the scripted decision node, refer to the [User identity attributes and properties reference](../identities/user-identity-properties-attributes-reference.html#reference-tables). | 5. Add the required Allowlisted Session Property Names from the journey to the [Session Property Whitelist Service](../am-reference/services-configuration.html#realm-amsessionpropertywhitelist) (Under Native Consoles > Access Management, go to Realms > Realm Name > Services > Session Property Whitelist Service). #### Configure the Microsoft 365 application 1. In the Advanced Identity Cloud admin console, go to Applications, and click [icon: grid_view, set=material, size=inline] Browse App Catalog. 2. In the Browse App Catalog modal, select Microsoft 365, and click Next. 3. Review the Application Integration information, and click Next. 4. In the Application Details window, specify the name, description, application owners, and logo for the application. 5. Click Create Application. 6. On the Sign On tab, click Set Up SSO. 7. In the Set Up Single Sign-on modal ([field descriptions](#sso-microsoft-365-settings)): 1. If you've set up multiple custom domains, select the applicable Sign on domain, and click Next; otherwise, continue to the next step. | | | | - | ----------------------------------------------------------------------------------------------- | | | You must set the [Cookie domain](../realms/cookie-domains.html) for the selected custom domain. | 2. Enter the Microsoft Entra ID Domain Name. 3. Select a Journey. 4. Click Save. The Sign On tab displays additional settings ([field descriptions](#sso-microsoft-365-settings)). 8. In the Next Steps section, click View PowerShell cmdlets. 9. In the PowerShell Cmdlets modal, copy the Set Up SSO PowerShell Cmdlet script. 10. Open Windows PowerShell, paste the copied command, and run it. 11. To test the SSO connection, at the bottom right of the page, click Try it out and follow the SSO flow. #### Microsoft Entra hybrid join requirements To set up SSO for Microsoft Entra hybrid joined devices, do the following after completing [Microsoft 365 requirements](#sso-microsoft-365-requirements): 1. [Create a new managed object type](../idm-objects/creating-modifying-managed-objects.html) for devices with the following requirements: * Don't use underscores in the object `name`. * Add two required, searchable string properties: `computerName` and `immutableId`. 2. Provision devices: 1. [Create an Advanced Identity Cloud Active Directory authoritative application](register-an-application.html). 2. [Set up application provisioning](provision-an-application.html#provision-active-directory) with the following important details: * Include `computer` in the User Object Classes field. * Include `computer` in the Object Classes to synchronize field. > **Collapse: Show provisioning application example** > > ![hybrid join1](_images/hybrid-join1.png) 3. Use the [Advanced Sync](provision-an-application.html#manage-advanced-sync) tab to map the following source attributes to the device managed object properties: * `source.sAMAccountName` to `computerName`. * `source.objectGUID` to `immutableId`. * [Apply a transformation script](provision-an-application.html#apply-a-transformation-script-to-a-mapping) to Base64-encode the `objectGUID`. > **Collapse: Show example transformation script** > > ```javascript > /* > Convert objectGUID in string format to Base64 format. > 1. Convert objectGUID to hex > 2. Reverse the byte order of the first three components of objectGUID > 3. Base64 encode > */ > var uuid = Packages.java.util.UUID.fromString(source); > > var buffer = Packages.java.nio.ByteBuffer.allocate(16); > buffer.putLong(uuid.getMostSignificantBits()); > buffer.putLong(uuid.getLeastSignificantBits()); > > var uuidBytes = buffer.array(); > var guidBytes = Packages.java.util.Arrays.copyOf(uuidBytes, uuidBytes.length); > > guidBytes[0] = uuidBytes[3]; > guidBytes[1] = uuidBytes[2]; > guidBytes[2] = uuidBytes[1]; > guidBytes[3] = uuidBytes[0]; > guidBytes[4] = uuidBytes[5]; > guidBytes[5] = uuidBytes[4]; > guidBytes[6] = uuidBytes[7]; > guidBytes[7] = uuidBytes[6]; > > var encoder = Packages.java.util.Base64.getEncoder(); > encoder.encodeToString(guidBytes); > ``` > **Collapse: Show application mapping example** > > ![hybrid join2](_images/hybrid-join2.png) 4. [Define the following advanced sync situation rules](provision-an-application.html#define-advanced-sync-rules) (leave all others as `ASYNC`): | Situation | Action | | --------- | -------- | | Missing | `CREATE` | | Confirmed | `UPDATE` | | Found | `UPDATE` | | Absent | `CREATE` | > **Collapse: Show situation rules example** > > ![hybrid join3](_images/hybrid-join3.png) 5. From the Reconciliation drop-down menu, select Reconcile and click Reconcile Now. 3. Configure a Service Principal Name (SPN) for Kerberos authentication in your on-premises AD: 1. On the Domain Controller, create or update an existing service account in AD for Kerberos. 2. In the serviceAccountName properties, select the following Account options: * This account supports Kerberos AES 128 bit encryption * This account supports Kerberos AES 256 bit encryption 3. Open Windows PowerShell, and run the following command to configure the SPN: ```powershell setspn -S HTTP/ ``` > **Collapse: Show example** > > ```powershell > setspn -S HTTP/openam-hgale-uidev-may4.forgeblocks.com aicKerberos > > Checking domain DC=hgaledomain,DC=lab > > Registering ServicePrincipalNames for CN=aicKerberos,CN=Managed Service Accounts,DC=hgaledomain,DC=lab > HTTP/openam-hgale-uidev-may4.forgeblocks.com > Updated object > ``` 4. [Configure WS-Trust](#ws-trust-config). | | | | - | --------------------------------------------------------------------------------------- | | | You must enable Kerberos Authentication in the WS-Trust Authentication Methods section. | 5. Register devices for hybrid join: 1. On the member server machine, open Windows PowerShell, and run the following command: ```powershell dsregcmd /status +----------------------------------------------------------------------+ | Device State | +----------------------------------------------------------------------+ AzureAdJoined : YES/NO EnterpriseJoined : NO DomainJoined : YES DomainName : hgaledomain ``` 2. If `AzureAdJoined` is `NO`, continue to the next step; otherwise, run the command: ```powershell dsregcmd /leave ``` 3. Sign on to the Azure portal, navigate to Microsoft Entra ID > Manage > Devices > All devices, and verify your device isn't listed. > **Collapse: Show example** > > ![hybrid join4](_images/hybrid-join4.png) 4. On the member server machine, open Windows PowerShell, and run the following command to join the device: ```powershell dsregcmd /join /debug ``` > **Collapse: Show example output** > > ```powershell > dsregcmd::wmain logging initialized. > dsregcmd::wmain logging initialized. > DsrCmdAccountMgr::IsDomainControllerAvailable: DsGetDcName success { domain:hgaledomain.lab forest:hgaledomain.lab domainController:\\XXXXXXX-XXXXXXX.hgaledomain.lab isDcAvailable:true } > PreJoinChecks Complete. > preCheckResult: Join > isPrivateKeyFound: undefined > isJoined: undefined > isDcAvailable: YES > isSystem: YES > keyProvider: undefined > keyContainer: undefined > dsrInstance: undefined > elapsedSeconds: 0 > resultCode: 0x0 > Automatic device join pre-check tasks completed. > TenantInfo::Discover: Join Info { TenantType = Federated; AutoJoinEnabled = 1; TenandID = 07e...90; TenantName = hgale.ping-eng.com } > GetComputerTokenForADRS: Get token for ADRS > GetComputerTokenForADRS: Auth code URL: "https://login.microsoftonline.com/07e...90/oauth2/authorize" > GetComputerTokenForADRS: Token request authority: "https://login.microsoftonline.com/common" > AdalLog: Token is not available in the cache ; HRESULT: 0x0 > AdalLog: Authority validation is enabled ; HRESULT: 0x0 > AdalLog: Authority validation is completed ; HRESULT: 0x0 > AdalLog: AggregatedTokenRequest::AcquireToken get refresh token info ; HRESULT: 0x0 > AdalLog: AggregatedTokenRequest::AcquireToken- refresh token is not available ; HRESULT: 0x0 > AdalLog: AggregatedTokenRequest::AcquireToken- returns false ; HRESULT: 0x0 > AdalLog: AggregatedTokenRequest::UseWindowsIntegratedAuth w Tenant ; HRESULT: 0x0 > AdalLog: HRESULT: 0x4aa90010 > AdalLog: AggregatedTokenRequest::UseWindowsIntegratedAuth- received realm info ; HRESULT: 0x0 > AdalLog: AggregatedTokenRequest::GetAppliesTo: using resource ID "urn:federation:MicrosoftOnline" for authority "https://login.microsoftonline.com/common". ; HRESULT: 0x0 > AdalLog: HRESULT: 0x4aa90010 > AdalLog: Webrequest opening connection ; HRESULT: 0x0 > AdalLog: HRESULT: 0x4aa90010 > AdalLog: Webrequest has valid state ; HRESULT: 0x0 > AdalLog: WebRequest Status:200 ; HRESULT: 0x0 > AdalLog: Webrequest returns success for oauth response ; HRESULT: 0x0 > AdalLog: HRESULT: 0x4aa9000f > AdalLog: HRESULT: 0x4aa9000d > Join request ID: c0...8c > Join response time: Mon, 04 Aug 2025 15:16:23 GMT > Join HTTP status: 200 > DsrCmdJoinHelper::Join: AutoEnrollAsComputer completed successfully > DSREGCMD_END_STATUS > AzureAdJoined : YES > EnterpriseJoined : NO > DeviceId : 42...5d > Thumbprint : 47...6D > DeviceCertificateValidity : [ 2025-08-04 15:16:23.000 UTC — 2035-08-04 15:16:23.000 UTC ] > KeyContainerId : 42...77 > KeyProvider : Microsoft Software Key Storage Provider > TpmProtected : NO > TenantName : > TenantId : 07...90 > Idp : login.windows.net > AuthCodeUrl : https://login.microsoftonline.com/07...90/oauth2/authorize > AccessTokenUrl : https://login.microsoftonline.com/07...90/oauth2/token > MdmUrl : > MdmTouUrl : > MdmComplianceUrl : > SettingsUrl : > JoinSrvVersion : 1.0 > JoinSrvUrl : https://enterpriseregistration.windows.net/EnrollmentServer/device/ > JoinSrvId : urn:ms-drs:enterpriseregistration.windows.net > KeySrvVersion : 1.0 > KeySrvUrl : https://enterpriseregistration.windows.net/EnrollmentServer/key/ > KeySrvId : urn:ms-drs:enterpriseregistration.windows.net > WebAuthNSrvVersion : 1.0 > WebAuthNSrvUrl : https://enterpriseregistration.windows.net/webauthn/07...90/ > WebAuthNSrvId : urn:ms-drs:enterpriseregistration.windows.net > DeviceManagementSrvVer : 1.0 > DeviceManagementSrvUrl : https://enterpriseregistration.windows.net/manage/07...90/ > DeviceManagementSrvId : urn:ms-drs:enterpriseregistration.windows.net > DeleteFileW returned 0x00000001. > ``` 5. Confirm your device is hybrid joined: 1. Sign on to the Azure portal, navigate to Microsoft Entra ID > Manage > Devices > All devices, and verify your device is listed. > **Collapse: Show example** > > ![hybrid join5](_images/hybrid-join5.png) 2. Navigate to Microsoft Entra ID > Manage > Devices > Activity > Audit logs, and verify audit events for your device. > **Collapse: Show example** > > ![hybrid join6](_images/hybrid-join6.png) 3. On the member server machine, open Windows PowerShell, and run the following command to confirm `AzureAdJointed` is `YES`: ```powershell dsregcmd /status ``` > **Collapse: Show example output** > > ```powershell > +----------------------------------------------------------------------+ > | Device State | > +----------------------------------------------------------------------+ > > AzureAdJoined : YES > EnterpriseJoined : NO > DomainJoined : YES > DomainName : HGALEDOMAIN > ... > +----------------------------------------------------------------------+ > | SSO State | > +----------------------------------------------------------------------+ > > AzureAdPrt : NO > AzureAdPrtAuthority : > EnterprisePrt : NO > EnterprisePrtAuthority : > ``` 6. Retrieve the `AzureAdPrt`: 1. Sign out of the member server machine. 2. Sign on to the member server machine, open Windows PowerShell, and run the following command: ```powershell dsregcmd /status ``` > **Collapse: Show example output** > > ```powershell > +----------------------------------------------------------------------+ > | SSO State | > +----------------------------------------------------------------------+ > > AzureAdPrt : YES > AzureAdPrtUpdateTime : 2025-08-04 15:56:23.000 UTC > AzureAdPrtExpiryTime : 2025-08-18 15:56:22.000 UTC > AzureAdPrtAuthority : https://login.microsoftonline.com/07...90 > EnterprisePrt : NO > EnterprisePrtAuthority : > ``` #### Configure WS-Trust You can configure WS-Trust for your Microsoft 365 application only after the initial application setup. If you need to set up SSO for Microsoft Entra hybrid joined devices, complete [Microsoft Entra hybrid join requirements](#sso-microsoft-365-hybrid-join-requirements) first. 1. On the Sign On tab, select Enable WS-Trust. 2. In the WS-Trust Authentication Methods section, select one or more of the following options: * Username/Password Authentication: Allows users to authenticate with their username and password using WS-Trust. 1. Select the ImmutableID Attribute Name. This list contains all string properties for the managed user object. 2. Select the UPN Attribute Name. The attribute that maps to the User Principal Name (UPN) in Microsoft 365. Defaults to `Username` if not selected. This list contains all string properties for the managed user object. * Kerberos Authentication: Activate Kerberos authentication with your organization's realm. 1. Select the Kerberos Realm. You can add, edit, or delete Kerberos realms from this list. * Add * Edit * Delete To add a new Kerberos realm: 1. Click Add. 2. In the Add Kerberos Realm modal, enter the: * Unique AD Domain/Realm Name. * Domain/Realm Username. * Password. 3. Click Save. To edit a Kerberos realm: 1. Adjacent to an existing realm name, click [icon: edit, set=material, size=inline]. 2. In the Add Kerberos Realm modal, make changes and click Save. To delete a Kerberos realm: 1. Adjacent to the existing realm name, click [icon: edit, set=material, size=inline]. 2. In the Add Kerberos Realm modal, click [icon: delete, set=material, size=inline] Delete Realm. 3. In the Delete Kerberos Realm confirmation modal, click Delete. 2. Select a Managed Object Name for the location where the device information is locally stored. This list contains all custom managed objects. * x.509 Authentication: Use certificate-based authentication for WS-Trust sign-on. 1. Select the ImmutableID Attribute Name. This list contains all string properties for the managed user object. 2. Select the UPN Attribute Name. The attribute that maps to the User Principal Name (UPN) in Microsoft 365. Defaults to `Username` if not selected. This list contains all string properties for the managed user object. 3. Enter the Allowed Issuer DNs. The system only accepts tokens that match a certificate issuer DN from this list. | | | | - | ------------------------------------------------------------------------------------------------------- | | | Make sure to [add a trusted certificate](#sso-manage-ms-365-x509-certs) for this authentication method. | 3. Click Save. 4. When you enable, disable, or edit the WS-Trust settings and save the configuration, the PowerShell cmdlet adds or removes the `ActiveSignInURI` and `MetadataExchangeUri` lines. Run the updated cmdlet: 1. Scroll back to the top of the page, and in the Next Steps section, click View PowerShell cmdlets. 2. In the PowerShell Cmdlets modal, copy the Update SSO Settings PowerShell Cmdlet script. 3. Open Windows PowerShell, paste the copied command, and run it. #### Microsoft 365 update SSO settings To update the SSO settings for your Microsoft 365 Advanced Identity Cloud application: 1. In the Advanced Identity Cloud admin console, go to Applications, and click the existing Microsoft 365 application. 2. Select the Sign On tab, and from the Next Steps section, click View PowerShell cmdlets. 3. In the PowerShell Cmdlets modal, copy the Update SSO Settings PowerShell Cmdlet script. 4. Open Windows PowerShell, paste the copied command, and run it. #### Microsoft 365 Sign On settings The following table displays all Microsoft 365 Sign On field descriptions: | Field | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Sign on domain | The Advanced Identity Cloud sign on domain to use for SSO. You must set the Cookie domain for the selected custom domain. | | Microsoft Entra ID Domain Name | The custom domain value from your Entra ID account. You can find your custom domain in the Entra ID Admin Center by navigating to Domain Names. Use the format `example.com`. | | Name ID Format | Specifies the format of the Subject Name Identifier attribute in the WS-Fed security token. | | Journey | The SSO journey. | | WS-Trust | Select this option to activate support for token-based authentication using the WS-Trust protocol, typically for use with legacy SOAP-based applications such as older versions of Microsoft Outlook or SharePoint. | | WS-Trust Authentication Methods When you enable, disable, or edit WS-Trust settings, you must run the updated PowerShell cmdlets. | | | Username/Password Authentication | Allows users to authenticate with their username and password using WS-Trust.1) Select the ImmutableID Attribute Name that uniquely identifies the user. This list contains all string properties for the managed user object. 2) Select the UPN Attribute Name. The attribute that maps to the User Principal Name (UPN) in Microsoft 365. Defaults to `Username` if not selected. This list contains all string properties for the managed user object. | | Kerberos Authentication | Activate Kerberos authentication with your organization's realm using WS-Trust.1) Select the Kerberos Realm used to authenticate users using Kerberos tokens. You can add, edit, or delete Kerberos realms from this list. * Add * Edit * Delete To add a new Kerberos realm: 1. Click Add. 2. In the Add Kerberos Realm modal, enter the: * Unique AD Domain/Realm Name. * Domain/Realm Username. * Password. 3. Click Save. To edit a Kerberos realm: 1. Adjacent to an existing realm name, click [icon: edit, set=material, size=inline]. 2. In the Add Kerberos Realm modal, make changes and click Save. To delete a Kerberos realm: 1. Adjacent to the existing realm name, click [icon: edit, set=material, size=inline]. 2. In the Add Kerberos Realm modal, click [icon: delete, set=material, size=inline] Delete Realm. 3. In the Delete Kerberos Realm confirmation modal, click Delete. 2) Select the custom Managed Object Name used to locally store device information. | | x.509 Authentication | Use certificate-based authentication for WS-Trust sign-on.1) Select the ImmutableID Attribute Name. This list contains all string properties for the managed user object. 2) Select the UPN Attribute Name. The attribute that maps to the User Principal Name (UPN) in Microsoft 365. Defaults to `Username` if not selected. This list contains all string properties for the managed user object. 3) Enter the Allowed Issuer DNs. The system only accepts tokens that match a certificate issuer DN from this list. Make sure to add a trusted certificate for this authentication method. | | Advanced settings You must add these properties to: Native Consoles > Access Management > Realms > Realm Name > Services > Session Property Whitelist Service. The scripted decision node. If you have used different property names, you must update these fields. Learn more in Microsoft 365 requirements. | | | ImmutableID | The path in the authenticated session that maps to the attribute that uniquely identifies a user in Microsoft 365. Default value `/properties/am.protected.immutableID`. | | Subject | The path in the authenticated session that maps to the Subject in Microsoft 365. Default value `/properties/am.protected.userPrincipalName`. | | UPN | The path in the authenticated session that maps to the User Principal Name (UPN) in Microsoft 365. Default value `/properties/am.protected.userPrincipalName`. | #### Manage Microsoft 365 application signing certificates When you configure SSO for Microsoft 365, the application generates a signing certificate to secure communication with Microsoft. It's best practice to rotate this certificate periodically. You might need to do this for several reasons: * The existing certificate is within three months of its expiration date. * To comply with regulatory security requirements. * To adhere to internal company policies. The signing certificate is shared across all your Microsoft 365 applications. To manage signing certificates: 1. In the Advanced Identity Cloud admin console, go to Applications, and select one of your Microsoft 365 applications. 2. On the Sign On tab, scroll down to the Signing Certificate section. You can view, download, and rotate your certificates. | | | | - | -------------------------------------------------------------------------------------------------- | | | If an active certificate's expiration date is within three months, its status shows as `Expiring`. | ##### View and download the signing certificate You can review the certificate's details, including its issuer and subject, serial number, and expiration date. Downloading a copy is also useful for: * Troubleshooting by comparing it with your Microsoft 365 configuration. * Retaining a copy for audit purposes. To view and download the certificate: 1. Click the certificate to display its details. 2. In the Certificate Details modal, review the certificate details. 3. To save a local copy, click Download Certificate. 4. Click Done. ##### Rotate the signing certificate The rotation process replaces the currently active certificate with a new one. It involves three stages: generating a new inactive certificate in Advanced Identity Cloud, updating Microsoft 365 applications to trust it, and then activating the new certificate in Advanced Identity Cloud. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can have only one inactive certificate at a time. If an inactive certificate already exists and you need to create a new one, you must delete the old one first. To do this, click the ellipsis ([icon: ellipsis-h, set=fa]) icon next to the inactive certificate and select Delete. | To rotate the signing certificate: 1. Click [icon: plus, set=fa]Generate New Certificate. The new certificate appears in the list with an `Inactive` status. 2. Update Microsoft 365 applications to trust the new certificate: 1. In the Next Steps section, click View PowerShell Cmdlets. 2. In the PowerShell Cmdlets modal, copy the Update SSO Settings PowerShell Cmdlet script. 3. Open Windows PowerShell, paste the copied command, and run it. 4. Repeat steps b and c for each of the applications listed in the PowerShell Cmdlets modal. 5. Return to the PowerShell Cmdlets modal and click Done. 3. Activate the new certificate: | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Don't proceed unless you've successfully run the Powershell cmdlets for ALL Microsoft 365 applications in the previous step. Activating the new certificate permanently deletes the old one. All users of all Microsoft 365 applications will be locked out unless the apps have been updated to trust the new certificate. | 1. Click the ellipsis ([icon: ellipsis-h, set=fa]) icon next to the inactive certificate and select Activate. 2. Click Activate Certificate. The old certificate is removed and the new certificate's status changes to `Active`. #### Manage Microsoft 365 application trusted certificates When you configure x.509 authentication for WS-Trust, Advanced Identity Cloud uses trusted certificates to validate the identity of clients. These certificates are shared across all your Microsoft 365 applications. To manage trusted certificates: 1. In the Advanced Identity Cloud admin console, go to Applications, and select one of your Microsoft 365 applications. 2. On the Sign On tab, scroll down to the Trusted Certificates section. You can view, import, and delete your certificates. ##### View trusted certificate details You can review a certificate's details, including its issuer, subject, and expiration date. To view the certificate details: 1. Click the certificate to display its details. 2. In the Certificate Details modal, review the certificate details. 3. Click Done. ##### Add a trusted certificate You can add a trusted certificate in PEM, CRT, and CER formats. To add a trusted certificate: 1. Click [icon: plus, set=fa]Add Certificate. 2. In the Add x.509 Certificate modal, click Browse, select the certificate, and then click Upload. 3. In the Certificate Details modal, review the certificate details, and click Done. The new certificate displays in the Trusted Certificates section. ##### Delete a trusted certificate To delete a trusted certificate: 1. Click the ellipsis ([icon: ellipsis-h, set=fa]) icon next to the certificate and select Delete. 2. In the confirmation modal, click Delete. ### Custom WS-Fed | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Custom WS-Fed applications require WS-Federation, which is an [add-on capability](../product-information/add-on-capabilities.html). Contact your Ping Identity representative to add WS-Federation to your PingOne Advanced Identity Cloud subscription. | Custom WS-Fed applications let you set up SSO using the [WS-Federation](https://en.wikipedia.org/wiki/WS-Federation) identity protocol and the [Passive Requestor Profile](https://en.wikipedia.org/wiki/WS-Federation_Passive_Requestor_Profile) (where the passive requestor is an end user's browser). Advanced Identity Cloud serves as the identity provider (IdP) and the connected partner acts as the service provider (SP) that's identified by a unique partner realm. When an end user tries to access a protected resource, the SP redirects them to the IdP to authenticate. The user signs on with their Advanced Identity Cloud credentials. After successful authentication, Advanced Identity Cloud generates a token and then redirects the user back to the SP with the token. The SP validates the token and grants the user access to the protected resource. #### Custom WS-Fed requirements 1. Enable the WS-Fed [add-on capability](../product-information/add-on-capabilities.html). 2. Configure the SP for WS-Fed. 3. Create a journey with authenticated user attributes required for the WS-Fed response message. You can use a scripted decision node for this. > **Collapse: Show example journey** > > ![Example journey for Microsoft 365 SSO](_images/ui-applications-ms365-sso-example-journey.png) > **Collapse: Show example for scripted decision node** > > ```javascript > /* > - Data made available by nodes that have already executed are available in the sharedState variable. > - The script should set outcome to either "true" or "false". > - Note: This script isn't fault-tolerant. It's meant to give an idea about how script nodes might be used in the context of the webinar. > */ > var fr = JavaImporter(org.forgerock.openam.auth.node.api.Action); > > // get the user id from the node state. > var userId = nodeState.get("_id").asString(); > > // get the username from the user repository. > var username = idRepository.getAttribute(userId, "uid").iterator().next(); > > // add username to the session property. > action = fr.Action.goTo("true") > .putSessionProperty("am.protected.username", username) > .build(); > > outcome = "true"; > ``` | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For a list of AM attribute names you can use in the scripted decision node, refer to the [User identity attributes and properties reference](../identities/user-identity-properties-attributes-reference.html#reference-tables). | 4. Add the required Allowlisted Session Property Names from the journey to the [Session Property Allowlist Service](../am-reference/services-configuration.html#realm-amsessionpropertywhitelist) located in Native Consoles > Access Management, go to Realms > Realm Name > Services > Session Property Whitelist Service. #### Configure the custom WS-Fed application | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | You can create only one custom WS-Fed SSO application per partner realm. Additionally, you can't use the Microsoft Online partner realm to configure a custom WS-Fed application. Instead, use the [Microsoft 365 application](#sso-microsoft-365) to configure your use case. | 1. In the Advanced Identity Cloud admin console, go to Applications and click [icon: add, set=material, size=inline] Custom Application. 2. In the Add a Custom Application modal, select WS-Fed and click Next. 3. In the Application Details window, specify the name, description, application owners, and logo for the application. 4. Click Save. Advanced Identity Cloud creates the application. 5. On the Sign On tab, click Set Up SSO. 6. In the Set Up Single Sign-on modal ([field descriptions](#sso-custom-wsfed-settings)): 1. If you've set up multiple custom domains, select the applicable Sign on domain and click Next. Otherwise, continue to the next step. | | | | - | ----------------------------------------------------------------------------------------------- | | | You must set the [Cookie domain](../realms/cookie-domains.html) for the selected custom domain. | 2. Enter the Partner's Realm. 3. Select a Journey created as a part of the [Custom WS-Fed requirements](#sso-custom-wsfed-requirements). 4. Select a Name ID Format. 5. Enter the Subject Path. 6. Enter the Username Path. 7. Enter the Service Endpoint. 8. (Optional) Click Show advanced settings to set any of the following options: 1. Sign-in URL 2. Redirect URLs area: 1. Valid Domain 2. Allow any query parameter and/or fragment 3. Valid Path 3. Service Provider Attributes area: 1. Name 2. Name Format 3. Attribute Path 9. Click Save. 7. In the Next Steps section, click Download certificate. The SP uses this certificate to validate incoming tokens from Advanced Identity Cloud. 8. To test the SSO connection, at the bottom right of the Settings section, click Try it out and follow the SSO flow. #### Custom WS-Fed Sign On settings The following table displays all custom WS-Fed Sign On field descriptions: | Field | Description | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Partner's Realm | The unique identifier of your SP partner. | | Journey | The SSO journey. | | Name ID Format | The format of the Subject Name Identifier attribute in the WS-Fed security token. | | Subject Path | The JSON pointer to the subject attribute in the authenticated session.Default value: `/properties/am.protected.username` | | Username Path | The JSON pointer to the location of the username in the authenticated session. This is validated against the incoming user identifier, if any, collected during authentication to determine if the user has an existing session.Default value: `/properties/am.protected.username` | | Service Endpoint | The SP URL to send security tokens to after authentication. | | Advanced settings | | | Sign-in URL (optional) | The URL to redirect users to for authentication. If left empty, the value of the Service Endpoint field is used. | | Redirect URLs (optional) | Specify additional valid URLs for redirection. | | Valid Domain | A leading wildcard (\*) is allowed to match subdomains. For example, `*.domain.com`. | | Allow any query parameter and/or fragment | If this is selected, the Valid Path field can't contain any query or fragment. | | Valid Path (optional) | Must start with a forward slash and not contain wildcards. Leave blank to allow any path. | | Service Provider Attributes (optional) | Define additional attributes to be included in the token issued to the SP. | | Name | The name of the attribute. | | Name Format | The format of this attribute in the WS-Fed security token. | | Attribute Path | The JSON pointer to the location of this claim's value in the authenticated session. For example, `/properties/am.protected.organization`. You must add these optional SP attribute properties to: Native Consoles > Access Management > Realms > Realm Name > Services > Session Property Whitelist Service. The Scripted Decision node. If you've used different property names, you must update these fields. Learn more in Custom WS-Fed requirements. | #### Manage the custom WS-Fed application signing certificate When you configure SSO for WS-Fed, the application generates a signing certificate to secure communication with the SP. It's best practice to rotate this certificate periodically. You might need to do this for several reasons: * The existing certificate is within three months of its expiration date. * To comply with regulatory security requirements. * To adhere to internal company policies. The signing certificate is unique to your custom WS-Fed application. To manage signing certificates: 1. In the Advanced Identity Cloud admin console, go to Applications and select the custom WS-Fed application. 2. On the Sign On tab, scroll down to the Signing Certificate section. From here, you can view, download, and rotate your certificates. | | | | - | -------------------------------------------------------------------------------------------------- | | | If an active certificate's expiration date is within three months, its status shows as `Expiring`. | ##### View and download the signing certificate You can review the certificate's details, including its issuer and subject, serial number, and expiration date. You must download a copy and update the SP to trust this certificate. Retaining a local copy is also useful for audit purposes. To view and download the certificate: 1. Click the certificate to display its details. 2. In the Certificate Details modal, review the certificate details. 3. To save a local copy, click Download Certificate. 4. Click Done. ##### Rotate the signing certificate The rotation process replaces the currently active certificate with a new one. It involves three stages: 1. Generating a new inactive certificate in Advanced Identity Cloud. 2. Updating the SP with the new certificate. 3. Activating the new certificate in Advanced Identity Cloud. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can have only one inactive certificate at a time. If an inactive certificate already exists and you need to create a new one, you must delete the old one first. To do this, click the ellipsis ([icon: ellipsis-h, set=fa]) icon next to the inactive certificate and select Delete. | To rotate the signing certificate: 1. Click [icon: plus, set=fa]Generate New Certificate. The new certificate appears in the list with an `Inactive` status. 2. Update the SP configuration to use the new certificate for token validation. 3. Activate the new certificate: | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Activating the new certificate permanently deletes the old one. To prevent authentication failures, ensure you update the SP to trust this certificate. | 1. Click the ellipsis ([icon: ellipsis-h, set=fa]) icon next to the inactive certificate and select Activate. 2. Click Activate Certificate. The old certificate is removed and the new certificate's status changes to `Active`. ## Next step * [icon: check-square-o, set=fa][Application management](applications.html) * [icon: check-square-o, set=fa][App catalog](app-catalog.html) * [icon: check-square-o, set=fa][Register an application](register-an-application.html) or [Register a custom or SSO application](register-a-custom-application.html) * [icon: square-o, set=fa]*[Provision an application](provision-an-application.html)* * [icon: square-o, set=fa][Manage end users and roles](manage-users-and-roles.html) * [icon: square-o, set=fa][Manage application registrations](manage-app-status.html)