--- title: Register a WS-Federation or WS-Trust application description: Configure Microsoft 365 and custom WS-Fed SSO applications in Advanced Identity Cloud, including WS-Trust, Kerberos authentication, and certificate management component: pingoneaic page_id: pingoneaic:app-management:register-an-sso-application canonical_url: https://docs.pingidentity.com/pingoneaic/app-management/register-an-sso-application.html llms_txt: https://docs.pingidentity.com/pingoneaic/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Application Management", "Setup & Configuration"] section_ids: 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 sso-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 --- # Register a WS-Federation or WS-Trust 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). | Applications that use the WS-Federation or WS-Trust protocols let end users access external systems using their Advanced Identity Cloud credentials. You can't configure provisioning for SSO applications. ## 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, learn more in 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](../identities/advanced-sync-situation-rules.html) (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. This is the managed user property that maps to the Microsoft 365 User Principal Name (UPN). Advanced Identity Cloud uses this attribute to authenticate the user during WS-Trust Username/Password Authentication. If you don't select a value, it defaults to `Username`. | | | | - | ------------------------------------------------------------------------------------------------ | | | For existing Microsoft 365 applications, re-save the application for this change to take effect. | * 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. This is the managed user property that maps to the Microsoft 365 User Principal Name (UPN). * Advanced Identity Cloud uses this attribute to authenticate the user during WS-Trust Username/Password Authentication. * If you don't select a value, it defaults to `Username`. * For existing Microsoft 365 applications, re-save the application for this change to take effect. | | 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. | | | Logout Mode | Choose how Advanced Identity Cloud handles logout for the Microsoft 365 application. Selecting `PingAM` signs off the user by invalidating the authenticated session and the tenant session cookie. Default value `None`. | | Always authenticate user | Select this option to always prompt the user for credentials when signing on to Microsoft 365. | | 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, learn more in 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 advanced options: 1. Logout Mode 2. Always authenticate user 3. Sign-in URL 4. Redirect URLs area: 1. Valid Domain 2. Allow any query parameter and/or fragment 3. Valid Path 5. Service Provider Attributes area: 1. Name 2. Name Format 3. Attribute Path 4. Multi-valued 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 | | | Logout Mode | Choose how Advanced Identity Cloud handles logout for the custom WS-Fed application. Selecting `PingAM` signs off the user by invalidating the authenticated session and the tenant session cookie. Default value `None`. | | Always authenticate user | Select this option to always prompt the user for credentials when signing on to the custom WS-Fed application. | | 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. | | Multi-valued | Enable if the claim's attribute path resolves to more than one value in the authenticated session. When selected, the claim is included as a multi-valued claim in the WS-Fed assertion. | ### 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`.