Configuring the web service for OpenID

4.1 Configuring the web service for OpenID

You can use either the standard authentication service (web.oauth2) or the standalone authentication service (web.oauth2.ext) to authenticate your users. The standalone authentication service does not require access to the MyID application server, but connects directly to the database; however, currently the standalone authentication service supports only FIDO as an authentication method.

For more information on the standalone authentication service, see section 2, Setting up the standalone authentication service.

Before you can use the MyID authentication service to verify the identity of an end user, you must configure the web service with the details of your external system and with the security protocols you want to use.

You can secure the request for an identity token in the following ways:

Using a shared secret.

When configuring your authentication service, you generate a secret code, then store a Base64-encoded SHA-256 hash of the code on the server; when you make the authentication code request, you provide your secret code securely over https, and the server compares it to the hash. The secret code is never stored on the server.

Important: You must keep the shared secret safe, as it can provide access to the features of the MyID authentication service. Do not use the same shared secret for end-user authentication and server-to-server API authentication.
Using PKCE.

For each authentication code request, you generate a secret code (known as the code verifier), then pass a Base64 URL-encoded SHA-256 hash of the code (known as the code challenge) in the request. When you exchange the authentication code for an identity token, you provide the code verifier, which the server compares to the code challenge to verify that the same system requested the original authentication code.

For more information on PKCE, including details of requirements for the code verifier and code challenge, see the Proof Key for Code Exchange by OAuth Public Clients RFC:

tools.ietf.org/html/rfc7636

You can use one or both of these methods. The examples in this document assume that you are using a combination of both methods.

For stateful web sites, where for example the server uses cookies to map stateful sessions between the client and the web server, it is recommended to configure the authentication service to require a client secret; you do not have to use PKCE, but you can use it in addition to the client secret if you want.

For single-page apps, which run entirely on the client PC, you must secure the request for authentication using PKCE; a shared secret is not appropriate.

Note: You must use TLS to ensure the security of the system. The MyID authentication service is configured to use TLS by default; you must not use OAuth2 OpenID Connect-based systems without TLS.

4.1.1 Creating a shared secret

If you are using a shared secret, you must generate an unguessable secret and create a hash to store on the server.

You are recommended to use a GUID for the secret.

If you are using the standalone authentication web service (web.oauth2.ext) you can use the provided GenClientSecret.ps1 PowerShell script to generate a GUID and create a SHA-256 hash converted to Base64:

On the web server, open a PowerShell window.
Navigate to the authentication service folder.

C:\Program Files\Intercede\MyID\web.oauth2.ext
Run the script:

.\GenClientSecret.ps1

The script generates a GUID to use as the shared secret, creates a SHA-256 hash from the GUID, then converts the hash to Base64; for example:

PS C:\Program Files\Intercede\MyID\web.oauth2> .\GenClientSecret.ps1

client secret: 82564d6e-c4a6-4f64-a6d4-cac43781c67c

SHA256+base64: kv31VP5z/oKS0QMMaIfZ2UrhmQOdgAPpXV/vaF1cymk=

Important: Do not use this example secret in your own system.
Take a note of the following values:
- client secret – you need this value for the client_secret parameter when posting to the token URL.
  
  See section 4.2.3, Requesting an identity token.
- SHA256+base64 – you need this value for the ClientSecrets parameter in the web service configuration file. The server does not store the secret, only the Base64-encoded hash.
  
  See section 4.1.2, Editing the configuration file.

The script uses the following code to generate the GUID and Base64-encoded hash:

Copy

Add-Type -AssemblyName System.Security
if ($args.count -ne 0)
{
  write-host "Usage: GenClientSecret"
  exit
}
$clientSecret = [guid]::NewGuid()

write-host "client secret: " $ClientSecret

$hasher = [System.Security.Cryptography.HashAlgorithm]::Create('sha256')
$hashBytes = $hasher.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($ClientSecret))

$Sha256Base64 = [Convert]::ToBase64String($hashBytes)
write-host "SHA256+base64: " $Sha256Base64

4.1.2 Editing the configuration file

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

If you are using a standalone web service, by default, this is:

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

This file is the override configuration file for the appsettings.json file for the web service.
Edit the file to include the following:
Copy
```
{
    "Clients": [
        {
            "ClientId":  "<my client ID>",
            "ClientName":  "<my client name",
            "AccessTokenLifetime":  <access lifetime>,
            "IdentityTokenLifetime": <identity lifetime>,
            "AllowedGrantTypes": [
                "authorization_code"
            ],
            "RequireClientSecret": true,
            "RequirePkce": true,
            "AllowAccessTokensViaBrowser": true,
            "RequireConsent": true,
            "ClientSecrets": [
                {
                    "Value":"<secret>"
                }
            ],
            "AllowedScopes": [
                "openid"
            ],
            "RedirectUris": [
                "<callback URL>"
            ],
            "AllowedCorsOrigins": [
                "<origin>"
            ],
            "Properties": {
                "Skin": "popover"
            }
        }
    ]
}
```
where:
- <my client ID> – the client ID you decided on; for example:
  
  myid.openid
  
  This represents your back-end system that intends to make calls to the MyID authentication service.
- <my client name> – an easily readable name for your client system; for example:
  
  My OpenID System
- <access lifetime> – the time (in seconds) that the access token is valid. The default is 3600 – 1 hour.
- <identity lifetime> – the time (in seconds) that the identity token is valid. The default is 300 – 5 minutes.
- <secret> – if you are using a shared secret, set this to the Base64-encoded SHA-256 hash of the secret you created; for example:
  
  kv31VP5z/oKS0QMMaIfZ2UrhmQOdgAPpXV/vaF1cymk=
  
  See section 4.1.1, Creating a shared secret.
- <callback URL> – the URL of the web page on your system to which the authorization code will be returned.
- <origin> – used for Cross-Origin Resource Sharing (CORS). If the web page that calls the authentication service is on a different origin from the authentication service, you must add the origin to this list.
  
  Note: Make sure you use an origin, and not an URL, when configuring CORS. For example: https://myserver/ is an URL, while https://myserver is an origin.
You can set the following options:
- RequireClientSecret – set this to true if you are using a shared secret to secure the request.
- RequirePkce – set this to true if you are using PKCE to secure the request.
  
  Note: You must use a shared secret, PKCE, or both a shared secret and PKCE.
- RequireConsent – set this to true to allow the end-user to approve the external system's access to their identity information stored on your authentication service.
- AllowedScopes – set this to one of the values in the IdentityResources section of the appsettings.json file for the authentication service:
  - openid – returns the sub claim in the identity token; this is the subject ID of the end user, as stored in the UserAccounts.ObjectID field in the MyID database.
  - email – returns the email claim in the identity token; this is the email address of the user, as stored in the People.Email field in the MyID database.
    
    Note: The email claim is currently available only for FIDO authentication.
  - profile – returns the name claim in the identity token; this is the MyID logon name of the user, as stored in the UserAccounts.LogonName field in the MyID database.
- Properties – you can set the following:
  - Skin – currently only popover is available as a skin option for the authentication GUI. The authentication web page shows a background image with a popover representing the authentication UI; this is suitable for large windows. If you are displaying the authentication page in a small popup window, you can omit this option.
  - EnableFido2LoginBasicAssurance – set this to true to allow authentication using FIDO basic assurance authenticators, which provide only single-factor authentication. By default, this is set to false, to prevent access using basic assurance authenticators.
  - EnableFido2LoginHighAssurance – set this to true to allow authentication using FIDO high assurance authenticators, which provide multi-factor authentication. By default, this is set to true, to allow access using high assurance authenticators.
    
    When using FIDO with web.oauth2, authentication using high and basic assurance is controlled using the logon mechanisms feature; as the web.oauth2.ext standalone authentication service does not use the MyID application server, this feature is not available, and you must specify the logon mechanisms using the above options.
    
    For more information about basic and high assurance FIDO authenticators, see the Supported authenticators section in the FIDO Authenticator Integration Guide.
Important: If you have clients in the appsettings.json file and the appsettings.Production.json file, make sure the production file does not overwrite the entries in the base file. In these settings files, entries in arrays are determined by their index; therefore if you have four existing entries in the appsettings.json file, you must include four blank array entries {}, in the appsettings.Production.json file before you include your new client details. Alternatively, you can include the entire Clients array in the appsettings.Production.json file.

Note: By default, the appsettings.Production.json file contains the myid.adfs client section in the appropriate place; see section 3.4, Configuring the standalone authentication service for AD FS for details.

For example:
Copy
```
{
    "Clients": [
        {},
        {},
        {},
        {},
        {
            "ClientId": "myid.openid",
            "ClientName": "My OpenID System",
            "AccessTokenLifetime": 3600,
            "IdentityTokenLifetime": 300,
            "AllowedGrantTypes": [
                "authorization_code"
            ],
            "RequireClientSecret": true,
            "RequirePkce": true,
            "AllowAccessTokensViaBrowser": true,
            "RequireConsent": true,
            "ClientSecrets": [
                {
                    "Value": "kv31VP5z/oKS0QMMaIfZ2UrhmQOdgAPpXV/vaF1cymk="
                }
            ],
            "AllowedScopes": [
                "openid"
            ],
            "RedirectUris": [
                "https://myserver/mysystem/callback.asp"
            ],
            "AllowedCorsOrigins": [
                "http://myserver"
            ],
            "Properties": {
                "Skin": "popover"
            }
        }
    ]
}
```
If you already have an appsettings.Production.json file, back up the existing file, then incorporate the new client section above into the file.
Save the configuration file.
Recycle the web service app pool:
1. On the MyID web server, in Internet Information Services (IIS) Manager, select Application Pools.
2. Right-click the myid.web.oauth2.pool application pool, then from the pop-up menu click Recycle.
3. If you are using the standalone web service, right-click the myid.web.oauth2.ext.pool application pool, then from the pop-up menu click Recycle.
This ensures that the web service has picked up the changes to the configuration file.
Check that the authentication service is still operational by logging on to the MyID Operator Client.

Application setting JSON files are sensitive to such issues as comma placement; if the format of the file is not correct, the web service cannot load the file and will not operate, which may result in an error similar to:

HTTP Error 500.30 - ANCM In-Process Start Failure

See section 4.3, Troubleshooting for information on resolving problems that cause HTTP Error 500.30.

As an alternative to logging on to the MyID Operator Client (for example, if you are using the standalone authentication service), you can check the following URL:

https://<myserver>/web.oauth2/.well-known/openid-configuration

For the standalone authentication service, this is:

https://<myserver>/web.oauth2.ext/.well-known/openid-configuration

where <myserver> is the address of the MyID authentication service. This should return a block of JSON describing the endpoints and configuration of your authentication service.