nexus/knowledgebase/csd-wiki/ICSD/Add-OAuth-Authentication---Ops-Only_686065206.md

Add-OAuth-Authentication---Ops-Only_686065206

Introduction

OAuth is an open protocol to allow secure authorization. Setting up the OAuth authentication enables the suite to verify the identity of users and access users' private resources in the identity provider such as OpenID Connect. Users don't need to share their credentials.

OAuth users can access the tenant after the configurations are completed. The user profile is synced to Suite Administration after the user logs in to the tenant for the first time.

Limitations:

OAuth user can't be used for the following integration use cases:

• Publishing Operations Orchestration (OO) flows from OO Designer to OO Central
• SMAX and Design and Deploy (DND) integration
• DND and OO integration via DND integration user

Collect required info from customer

Before setting up OAuth authentication, collect the following information from the customer:

Field	Description
Client ID	The value of the Client ID that you get from the OpenID identity provider.
Client Secret	The value of the Client Secret that you get from the OpenID identity provider.
HTTP Method	The HTTP method of getting a user's information from the endpoint. The supported values are "GET" and "POST". Caution: By selecting The GET option, you are disabling or bypassing security features, thereby exposing the system to increased security risks. By using this option, you understand and agree to assume all associated risks and hold OpenText harmless for the same.
IDP URL	The endpoint or URL path provided by the OpenID Identity Provider. If User Info Endpoint, Token Endpoint, Authentication Endpoint, and Logout Endpoint are defined as relative paths, the IDP URL will be used as the base URL to construct the endpoint URLs.
Username Attribute	The attribute to define a username.
User Info Endpoint	An OAuth 2.0 Protected Resource that returns Claims about the authenticated end user. For example, /userinfo.
Token Endpoint	The token endpoint of the OpenID identity provider. The Token Endpoint is used to obtain a Token Response. For example, /token.
Authentication Endpoint	The Authorization Endpoint performs authentication of an end user. This is done by sending the user agent to the authorization server's endpoint for authentication and authorization, using request parameters defined by OAuth 2.0 and additional parameters and parameter values defined by OpenID Connect. For example, /authorize.
Logout Endpoint	The token endpoint where you can end a session.
Proxy	The corporate proxy used to connect IdM pods to the OAuth authentication server.

Besides the above information, customer also needs to provide the claim attribute names for the following user attributes.

Setting	Required	Description
First Name	Yes	First name of the user.
Family Name	Yes	Family name of the user.
Middle Name	No	Middle name of the user.
Office Phone Number	No	Office phone number of the user.
Home Phone Number	No	Home phone number of the user.
Mobile Phone Number	No	Mobile phone number of the user.
Zip Code	No	Zip code of the user.
Language	No	Language of the user.
Customer UID	No	Unique ID.
Location	No	Location of the user.

Configure proxy

Before adding an OAuth authentication, check if your network is working.

To check if the endpoint is accessible in container:

1. Go to the container by running this command: kubectl exec -ti -n -c idm -- bash
2. Run a curl command to check if the token or userinfo is returned.

For example, for keycloak: curl -k https://:/auth/realms//protocol/openid-connect/userinfo

A sample successful connection looks like below: {"error":"invalid_request","error_description":"Token not provided"}

A failed connection looks like below: curl: (7) Failed to connect to : Connection refused

If the connection fails, add your company's proxy settings to the deployment:

1. Log in to a bastion node as root or a sudo user, and run the following command to update the IdM deployment:
   kubectl edit deployment idm -n <suite namespace> 
2. Press i and add the following to the env section:
   - name: HTTPS_PROXY   value: <proxy> - name: HTTP_PROXY   value: <proxy>
3. Press:wq to save the file and quit. Wait until the idm pod is running. You can run the following command to check the idm pod status:
   kubectl get pods -n <suite namespace> | grep idm

To add the OAuth authentication, create a configuration for OAuth, and then create a configuration group for the OAuth configuration.

Create an OAuth configuration

To create an OAuth configuration, follow these steps:

1. In Suite Administration, click the IdM settings tab in the tenant detail page. The system opens the Authentication page for the corresponding organization in the IdM Admin Portal of the suite.
2. From the CONFIGURATIONS section, click to add one authentication.
3. Select OAUTH as the authentication type from the drop-down list, and then click CREATE.
4. Enter the related OAuth configuration settings. You can get the information from your OpenID identity provider. See OMT doc Set up OAuth 2.0 authentication - OPTIC Management Toolkit (microfocus.com) for more information.

   Field	Required	Description
   Display Name	Yes	The display name of this configuration.
   Shared in same family	No	Share the authentication settings within the same family. The supported values are "false" and "true''. See OMT doc.
   Client ID	Yes	The value of Client ID that you get from the OpenID identity provider.
   Client Secret	Yes	The value of Client Secret that you get from the OpenID identity provider.
   HTTP Method	Yes	The HTTP method of getting a user's information from the endpoint. The supported values are "GET" and "POST". Caution: By selecting The GET option, you are disabling or bypassing security features, thereby exposing the system to increased security risks. By using this option, you understand and agree to assume all associated risks and hold OpenText harmless for the same.
   IDP URL	Yes	The endpoint or URL path provided by the OpenID Identity Provider. The URL set for "Redirect URL" will be directed to the IDP URL.
   Redirect URI	Yes	The value of redirect URI of the IDM URL for login. See OMT doc.
   Scope	Yes	The value of scope. For example, "openid email". See OMT doc.
   State Supported	No	Whether support the State Supported feature. The supported values are "false" and "true''. See OMT doc.
   Username Attribute	Yes	The attribute to define a username.
   User Info Endpoint	No	An OAuth 2.0 Protected Resource that returns Claims about the authenticated end user. For example, /userinfo.
   Token Endpoint	Yes	The token endpoint of the OpenID identity provider. The Token Endpoint is used to obtain a Token Response. For example, /token.
   Authentication Endpoint	Yes	The Authorization Endpoint performs authentication of an end user. This is done by sending the user agent to the authorization server's endpoint for authentication and authorization, using request parameters defined by OAuth 2.0 and additional parameters and parameter values defined by OpenID Connect. For example, /authorize.
   Logout Endpoint	No	The token endpoint where you can end a session.
   Additional Parameter	No	The additional parameter for authentication. See OMT doc.

5. Click SAVE.

Create a configuration group for OAuth

To create a configuration group for OAuth, follow these steps:

1. After you create an OAuth configuration, from the CONFIGURATION GROUPS section, click to add an authentication group.
2. In the Name field, enter oauth.
3. In the Display Name field, enter a display name for the authentication group.
4. In Authentication Group Type, select the authentication group type (or types).
   If you select WEB Default, IdM will use this authentication group by default when a user logs in through the UI. Changing the authentication method for UI logins using this option won't sync with Suite Administration. To effect this change, use the default login type field on the tenant's General tab within Suite Administration.
   Don't select the API Default option.
5. In the Configurations field, select the OAuth authentication configuration that you just created. You can add only one OAuth authentication configuration to the OAuth configuration group.
6. Click SAVE.

Example: configure OAuth authentication with Google accounts

To enable OAuth-based Google Sign-In on a SMAX tenant:

1. Log in to Suite Administration, go to Tenants, and select the tenant that you want to enable OAuth-based Google Sign-In.
2. Click the IdM settings tab in the tenant detail page, from the CONFIGURATIONS section, click to add one authentication.
3. Select OAUTH as the authentication type, and then click CREATE.
4. Enter the following OAuth configuration settings.

   Field	Description
   Display Name	The display name of this configuration.
   Client ID	The value of Client ID that you get from step 5 above.
   Client Secret	The value of Client Secret that you get from step 5 above.
   IDP URL	https://accounts.google.com
   Scope	openid profile email
   User Info Endpoint	https://openidconnect.googleapis.com/v1/userinfo
   Token Endpoint	https://oauth2.googleapis.com/token
   Authorization Endpoint	https://accounts.google.com/o/oauth2/v2/auth
   Logout Endpoint	https://accounts.google.com/Logout
   Additional Parameter	The additional parameter for authentication.

5. Click SAVE.

Example: configure OAuth authentication with Azure accounts

1. Go to IdM admin portal.
2. Click Authentication and click Add. In the dialog box that appears, select OAUTH and click Create.

After clicking Create, the following page will appear.

Check the information provided by the customer at the top of this page and use those info when configuring the fields here.

• Client Id: the application (client) ID.
• Client secret: the secret value.
• Http Method: Use the info provided by the customer
• Idp URIs: choose any endpoint URL in step 1.5, fragment the url and end with "/v2.0". Example: endpoint url: https://login.microsoftonline.com/856b813c-16e5-49a5-85ec-6f081e13b527/oauth2/v2.0/authorize fragment: https://login.microsoftonline.com/856b813c-16e5-49a5-85ec-6f081e13b527/oauth2/v2.0
• Username Attribute: Use the info provided by the customer
• Userinfo Endpoint: https://graph.microsoft.com/oidc/userinfo (in Azure, the userinfo endpoint is special, the way to get the URL will be introduced in the following document.)
• Token Endpoint: /token
• Authentication Endpoint: / authorize
• Logout Endpoint: Suggested: /logout. If you want to redirect to another place, you can attach the URL at the end, such as: /logout?post_logout_redirect_uri= https://:// (the URL structure should be corresponding with the vendor's reguirements, some vendor may not following the standardized protocol, please refer to the offical documents)

Related topic

Microsoft identity platform and OpenID Connect protocol [https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc#send-a-sign-out-request]