6.2.2 Encrypting the client secret

Because you are going to store the client secret in a configuration text file on the server, you must encrypt it for security purposes. MyID supports DPAPI for encrypting the client secret; this uses the logged-on Windows user (in this case, the MyID web service user) to encrypt the secret, and only the same Windows user can decrypt the secret.

To encrypt the client secret:

1. On the MyID web server, log on as the user under which the web.oauth2 service runs.

   By default, this is the MyID Web Service user; you can confirm this by checking which user is configured for the myid.web.oauth2.pool application pool in IIS.

   Note: It is important that you use this account to encrypt the secret, as no other accounts can decrypt the secret to use it.

2. Open a Windows PowerShell command prompt, and navigate to the web.oauth2 folder.

   By default, this is:

   C:\Program Files\Intercede\MyID\web.oauth2\

3. Run the following PowerShell script:

   .\DPAPIEncrypt.ps1 <secret>

   For example:

   .\DPAPIEncrypt.ps1 b5989015-bb9e-4533-874b-2b4a6a8280ed

   The script outputs an encrypted copy of the secret; for example:

   PS C:\Program Files\Intercede\MyID\web.oauth2> .\DPAPIEncrypt.ps1 b5989015-bb9e-4533-874b-2b4a6a8280ed

   AQAAANCMnd8BFdERjHoAwE/C [...] JwWwaKXWoS3i+ulxtmjVQyudpQ==

   (Encrypted output string truncated for documentation purposes.)

4. Copy the encrypted secret.

6.2.3 Configuring the web.oauth2 server for OpenID Connect

1. In a text editor, open the appsettings.Production.json file for the web service.

   By default, this is:

   C:\Program Files\Intercede\MyID\web.oauth2\appsettings.Production.json

   This file is the override configuration file for the appsettings.json file for the web service.

2. Add an entry to the ExternalProviders array.

   If the ExternalProviders array does not exist, add it at the top level of the file. For reference, the appsettings.json file contains an empty ExternalProviders array that allows you to confirm its location.

   Copy

   "ExternalProviders":[
     {
       "Name": "<name>",
       "LogonMechanismId": <logon mechanism>,
       "Action": "<action>",
       "OpenIdConnectOptions": {
         "ClientId": "<client ID>",
         "ClientSecret": "<client secret>",
         "Authority": "<authority URL>",
         "ResponseType": "code",
         "GetClaimsFromUserInfoEndpoint":true, 
         "Scope": [<scopes>],
         "CallbackPath": "<callback path>",
         "Prompt": "login"
       },
       "ClientSecretEncrypted":"<encrypted client secret>",
       "Mappings":[
         {}
       ]
     }
   ]

   where:

   • <name> – the label used for the authentication method in the MyID Authentication dialog.

   • <logon mechanism> – the ID of the logon mechanism. MyID provides the following logon mechanism IDs that you can use for OpenID Connect systems:

     • 121 – corresponds to External IDP 1.

     • 122 – corresponds to External IDP 2.

     • 123 – corresponds to External IDP 3.

   • <action> – one of the following actions:

     • Find – (default) the user must already exist in the MyID database; the claims from the external identity provider must identify a user already in the MyID database.

     • Create – if the user does not already exist in MyID, they are created. If the user does exist, that same user is used.

     • Update – the user must already exist in MyID. Mapped fields marked with Update:true are updated in MyID based on the value supplied by the external identity provider.

       See section 6.4, Mapping attributes for details of setting the update options for mapped fields.

     • CreateAndUpdate – if the user does not already exist in MyID, they are created. If the user does exist, that same user is used and any fields marked with Update:true are updated.

   • <client ID> – the client ID from your Microsoft Entra configuration.

   • <client secret> – the client secret you created in Microsoft Entra.

     Important: For production systems, you are recommended not to include the client secret in the appsettings.production.json file, but to encrypt the client secret and use the ClientSecretEncrypted option instead.

   • <authority URL> – the URL that hosts the OpenID configuration well-known endpoint. For example, for Microsoft Entra, this is:

     https://login.microsoftonline.com/<tenant id>/v2.0

   • <scopes> – an array of scopes that you want to obtain from the external identity provider.

     For example:

     "Scope": ["openid", "email", "profile", "user.read"],

     Note: user.read is an Entra-specific scope that allows more user data to be returned.

   • <callback path> – the path to which the response is returned. This must correspond to the redirect URI you set up.

     For example, set the callback path to:

     /loginOidc121

     If your server is myid.mydomain.com, the response is returned to:

     https://myid.mydomain.com/web.oauth2/loginOidc121

   • <encrypted client secret> – the encrypted client secret. See section 6.2.2, Encrypting the client secret.

   For example:

   Copy

   "ExternalProviders":[
     {
       "Name":"OpenID Connect",
       "LogonMechanismId":121,
       "Action":"CreateAndUpdate",
       "OpenIdConnectOptions":{
         "ClientId":"bb61c9f6-9a71-42ba-a156-05db9a7a6407",
         "ClientSecret":"",
         "Authority":"https://login.microsoftonline.com/2fad39ef-cead-489d-a755-c3b45c762c4a/v2.0",
         "ResponseType":"code",
         "GetClaimsFromUserInfoEndpoint":true,
         "Scope":[
           "openid",
           "email",
           "profile",
           "user.read"
         ],
         "CallbackPath":"/loginOidc121",
         "Prompt":"login"
       },
       "ClientSecretEncrypted":"AQAAANCMnd8BFdERjHoAwE/C [...] JwWwaKXWoS3i+ulxtmjVQyudpQ==",
       "Mappings":[
         {}
       ]
     }
   ]

6.2.4 Configuring MyID to use OpenID Connect

Once you have set up your OpenID Connect server, and configured the web.oauth2 server, you can configure MyID to make OpenID Connect available as a logon mechanism.

To enable the OpenID Connect logon mechanism:

1. In the MyID Operator Client, from the More category, select Configuration Settings > Security Settings.

   Alternatively, in MyID Desktop, from the Configuration category, select the Security Settings workflow.

2. Click the Logon Mechanisms tab.

3. Set one of the following options:

   • External IDP 1 – corresponds to logon mechanism ID 121.

   • External IDP 2 – corresponds to logon mechanism ID 122.

   • External IDP 3 – corresponds to logon mechanism ID 123.

   Use the logon mechanism that corresponds to the ID you specified in the LogonMechanismId field in the configuration file.

4. Click Save changes.

To make the OpenID Connect logon mechanism available to users:

1. In the MyID Operator Client, from the More category, select Configuration Settings > Edit Roles.

   Alternatively, in MyID Desktop, from the Configuration category, select the Edit Roles workflow.

2. Click Logon Methods.

3. In the Logon Mechanisms dialog, select the appropriate External IDP logon mechanism for each role you want to be able to log on using your OpenID Connect system.

4. Click OK, then click Save Changes.

6.2.5 Next steps

You can now map the attributes from the external identity provider to MyID attributes. See section 6.4, Mapping attributes.

See also section 6.6, Example OpenID Connect settings for a sample set of mappings for OpenID Connect.