XCreds Identity Provider Integration Guide

XCreds can be used with many identity providers. Configuration guides are available for several identity providers. When working with other identity providers, the best way to begin is to identify the minimum integration settings that XCreds will need from the identity provider. Then go to the configuration console for that identity provider and set up the corresponding elements for these integration settings. Once the identity provider console items are set up, use Profile Creator to generate a configuration profile and enter the settings values copied from the identity provider console.

Integration Settings

To prepare to enter the minimum integration settings, open Profile Creator and from the File menu choose Open.... Download and select the XCreds Basic Configuration file. Double click on the this item in the profile list to open it. This configuration will contain all the basic configuration options that may be needed for an identity provider.

Identity Provider Console

Go to the configuration console for the intended identity provider. As an example, for Azure this is https://portal.azure.com/ > App Registrations. For Google it is https://console.cloud.google.com/ > APIs & Services > Credentials. Create a new app integration for XCreds in the identity provider console. For OIDC identity providers, XCreds will need settings for clientID, discoveryURL, and redirectURI. Find values for these settings in the identity provider console and enter them in the corresponding fields in Profile Creator.

clientID and clientSecret

clientID will be a string of characters that is the identifier the new app registration created in the identity provide console. When this value is found in the identity provider console, check if there is another field near this called clientSecret or something similar. This may not be so for some identity providers but if it is present, the value for clientSecret should also be copied and entered in Profile Creator for clientSecret.

discoveryURL

The identity provider will define a url that ends with .well-known/openid-configuration. Find this url in the identity provider console and enter the value in Profile Creator for this setting.

redirectURI

The identity provider may have a setting for the app registration to define something called Redirect URI. If the identity provider has a field for this setting, enter a value for this in the identity provider console and in Profile Creator for this setting. An example value for this setting could be either xcreds://auth/ or https://127.0.0.1. If you are aware that another value for this setting is needed, use that value and confirm that it is entered in Profile Creator so XCreds has this value.

idpHostName

This setting is often not needed but may be required in some integrations. Unless it is known beforehand that this is needed for the current identity provider, it can be skipped. If it is required and not known, there will be an error when initially signing in with XCreds. If this is the case, inspect the XCreds logs and searching for idpHostName to discover the value that may be needed for this and add it in Profile Creator.

scopes

This setting may not be required unless the identity provider console shows a value for scopes. Check the identity provider console and add the value in Profile Creator if relevant.

Install Configuration

After entering all required values in Profile Creator, first remove any optional settings for which no values were entered. Then use the Profile Creator File menu to first save and then export the configuration file. Then find the saved mobileconfig file and install it macOS Settings > General > Device Management. Check that the config file was installed successfully and contains all the intended settings. Then confirm successful identity provider integration by signing out of macOS and test signing in with the XCreds login screen.

Troubleshooting

If any issues are encountered with testing the identity provider integration, first recheck the mobileconfig file values and confirm they match what was intended from the identity provider console. Next review the XCreds logs for any messages that may indicate other integration needs for the identity provider. The logs will also contain information on the data XCreds received from the identity provider regarding the sign-in event. This identity provider information may be useful to check that XCreds is receiving the expected data fields for the intended settings configured in Profile Creator.