Configuring integration with an OAuth2 server

The OAuth2 tab is used to configure a connection with an OAuth2 server.

  • This configured connection to an OAuth2 server is used when integrating the access control features of a gateway for a user logged on using the Workbench.

For applications that use an api, such as the JavaScript API Library, to access a gateway - the configuration of the OAuth2 tab is not required. This is because the login to the OAuth2 server and acquiring of an Access Token is done outside of deviceWISE.

OAuth 2.0 package installation and Roles definition

  1. Go to the Administration -> Packages tab and install the OAuth2 extension package. For more information on installing packages, see Packages.
  2. Configure Roles within deviceWISE based on existing ADFS groups
    1. Configure Active Directory Groups. 
    2. Adds ADFS users to the ADFS groups. 
    3. Use the Administration → Security tab to create Roles that have the same name as an ADFS group. 
    4. Use the Administration → Security tab and edit a security Policy. 
      • In the column that shows the new Role, configure the authorization to deviceWISE Resources as described in Policies tab.
    5. The Administration → Security tab definition of Users is not necessary, as the User to Role(s) assignment will be retrieved from ADFS.
  3. Add properties to configure the OAuth extension's behavior:
    1. The signature validation of the Access Token can be turned off by specifying the property "oauth2.token_validation=FALSE".
      • This can be useful when initially developing the OAuth 2.0 integration.
    2. RSA(256,384,512) signature is supported.
      • SSL certificate is supported by specifying the property "oauth2.ssl.cert_file=/PATH/TO/SSL/CERT".
    3. HMAC(SHA 256,384,512) signature is supported.
      • Secret MUST be used by specifying the property "oauth.hmac.secret=PLAINTEXT".
      For information on adding properties, see Properties file management.

Application access

  1. In the JavaScript application, login to the ADFS server and acquire an Access Token. This login workflow is outside of deviceWISE.
  2. Login to deviceWISE with the JavaScript devicewise.oauthLogin API, passing the Access Token.
  3. deviceWISE will validate the Access Token.
  4. Claim "exp" will be used to check if the Access Token has expired.

  5. Claim "group" will be used to create a deviceWISE user.

    deviceWISE will use the CN values as the roles of the user and use CommonName as part of the generated user name, the password of the generated user will be a non-modifiable random string.

  6. deviceWISE returns a session ID associated with the auto-generated-user in the devicewise.oauthLogin response.
  7. The JavaScript application can start using other APIs with the session ID returned from the login request.

Workbench user access

To support the integration of a user's Workbench logon to a gateway, using an OAuth2 server, the OAuth2 tab is used to configure the gateway's connection to the OAuth2 server.

Configuring the OAuth2 connection

The tab's parameters are:

Parameter Description
Access Token URL The endpoint for authentication server.
Client ID The client identifier issued to the client during the Application registration process.
Client Secret The client secret issued to the client during the Application Registration process.
Resource The resource server that the Client wants an access token to, as registered in the Identifier parameter of the Relying Party trust.
Redirect URI The redirect URI that is associated with the Client. This must match the RedirectUri value associated with the Client in ADFS.
Domain format for $(User) The options are:
  • None
  • Domain\User
  • User@Domain
Domain Shown when Domain format is Domain\User or User@Domain.

Related topics

LDAP

Security