OAuth 2.0 integration

The deviceWISE runtime supports the integration of its security feature with a centrally managed service like Active Directory Federation Service (OAuth 2.0).

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_path="/path/to/certs" and is added to search(non-recursive) for all certs under the path, if any of the certs matches the server key, access will be granted. If both oauth2.ssl.cert_path and oauth2.ssl.cert_file are specified in the properties file, oauth2.ssl.cert_file will be ignored.
    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.

Runtime 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.

Related Topics Link IconRelated Topics