Configuring OpenID authentication for RESTful API client workload

(Advanced use) Configure authentication through OpenID Connect, enabling single sign-on authentication for the RESTful API client to connect to the SYMREST service. OpenID authentication is supported only on Linux®. This topic is only applicable if using the SYMREST server to submit and manage client workload from IBM® Spectrum Symphony clients to your cluster through RESTful APIs; it is not required for managing IBM Spectrum Symphony applications and workload (sessions, and tasks), through RESTful API methods.

Before you begin

Your OpenID identity provider (IdP) must be set up according to your IdP's instructions. The IdP must follow OpenID Connect 1.0 specifications (see http://openid.net/developers/specs/).
The OpenID client must be registered to your IdP; ensure that you register the redirect URL of the OpenID client and acquire the client ID and client secret from your IdP.
A script that converts site-specific OpenID user IDs to EGO user IDs, which can then be used to access the cluster, must be available. The script must take each OpenID user's email ID as input and provide the corresponding EGO user ID as output in the format egoUsername:egoPassword (for example, Admin:Admin).

About this task

OpenID is an open standard that enables users to authenticate themselves to multiple entities without managing multiple accounts or sets of credentials. IBM Spectrum Symphony supports OpenID Connect 1.0.

For OpenID authentication, IBM Spectrum Symphony provides an OpenID authentication plug-in for connections between the SYMREST server and the RESTful API client; the lifecycle of the OpenID client is managed by the OpenIdClient service. Manage the OpenIdClient service much like any other system service in IBM Spectrum Symphony.

Procedure

Stop the SYMREST service:
```
egosh service stop SYMREST
```
Update the IDP section in the OpenIdClientConf.xml file at $EGO_CONFDIR/../../soam/profiles/conf/:
1. In the clientId parameter, specify the client ID acquired from your IdP.
2. In the clientSecret parameter, specify the client secret acquired from your IdP.
3. In the tokenEndpoint parameter, specify the Token Endpoint of your IdP. Usually, this URL can be found in the OpenID Provider Configuration Document.
4. In the authorizationEndpoint parameter, specify the Authorization Endpoint of your IdP. Usually, this URL can be found in the OpenID Provider Configuration Document.
5. In the redirectUri parameter, specify the redirect URL of the OpenIdClient. Ensure that you use the same URL registered to your IdP.
6. Optional: If your IdP supports OpenID Connect Session Management 1.0, in the endSessionEndpoint parameter, specify the end-session endpoint of your IdP.
7. Optional: If your IdP supports token revocation, in the revocationEndpoint parameter, specify the token revocation endpoint of your IdP.
For example:
```
<IDP clientId="cc05b13d-157c-4cb4-843a-e5836f1e4e2a"
         clientSecret="BLHfviEmlclPGN-xzOBF0JDlH2gCV2joeObIv2IrSD30iyRFGJ6f3mt1lb-wVupqXTjEueidpiHZuErmqDbhaw"
         tokenEndpoint="https://idp.com:8080/token"
         authorizationEndpoint="https://idp.com/authorize"
         endSessionEndpoint="https://idp.com:8080/endsession"
         revocationEndpoint="https://idp.com:8080/revoke"
         redirectUri="https://myOpenIdClienthost.example.com:8653/login"/>
```
Update the openid section in the symrest.json file at $EGO_CONFDIR/../../soam/profiles/conf/:
1. In the openIdClientUrl parameter, specify the URL of the OpenID client in the format https://host_name:port, where host_name identifies the host on which the OpenIdClient service is running in your cluster. You can find this URL in the $EGO_TOP/soam/openid/logs/OpenIdClient.log file; for example: myopenidclienthost.example.com.
2. In the openidEgoUserMappingScript parameter, specify the path to your own script that converts your OpenID users' email IDs to EGO user IDs. The script must take each OpenID user's email ID as input and provide the corresponding EGO user ID as output in the format egoUsername:egoPassword (for example, Admin:Admin).
3. Optional: In the caFileForOpenIDClient parameter, specify the path to a trusted CA certificate for the OpenID client. You can use the default self-signed CA certificate for testing purposes.
For example:
```
"openid":
{
    "openIdClientUrl": "https://myOpenIdClienthost.example.com:8653",
    "caFileForOpenIDClient": "$EGO_TOP/wlp/usr/shared/resources/security/cacert.pem",
    "openidEgoUserMappingScript": "/openid/users.sh"
}
```
Start the SYMREST and OpenIdClient services and confirm that they are running:
```
egosh service start SYMREST OpenIdClient
egosh service list -s SYMREST OpenIdClient
```
The SYMREST and OpenIDClient services are, by default, set to start manually. If you want these services to start automatically, edit the service profiles and set the StartType parameter to AUTOMATIC.

Results

Your OpenID configuration takes effect.

What to do next

Submit workload from the RESTful API client. See Managing workload from a RESTful API client.