Configure OAuth Login

An opt-in configuration for SSO using OAuth is supported and can be configured through the /opt/traffic_portal/public/traffic_portal_properties.json and /opt/traffic_ops/app/conf/cdn.conf files. OAuth uses a third party provider to authenticate the user. If enabled, the Traffic Portal Login page will still accept username and password for local accounts but will also allow authentication using OAuth. This will redirect to the oAuthUrl from /opt/traffic_portal/public/traffic_portal_properties.json which will authenticate the user then redirect to the new /sso page with an authorization code. The new /sso page will then construct the full URL to exchange the authorization code for a JSON Web Token, and POST this information to the user/login/oauth API endpoint. The user/login/oauth API endpoint will POST to the URL provided and receive JSON Web Token. The user/login/oauth API endpoint will decode the token, validate that it is between the issued time and the expiration time, and validate that the public key set URL is allowed by the list of whitelisted URLs read from /opt/traffic_ops/app/conf/cdn.conf. It will then authorize the user from the database and return a mojolicious cookie as per the normal login workflow.

Note

Ensure that the user names in the Traffic Ops database match the value returned in the sub field in the response from the OAuth provider when setting up with the OAuth provider. The sub field is used to reference the roles in the Traffic Ops database in order to authorize the user.

Note

OAuth providers sometimes do not return the public key set URL but instead require a locally stored key. This functionality is not currently supported and will require further development.

Note

The POST from the API to the OAuth provider to exchange the code for a token expects the response to have the token in JSON format with access_token as the desired field (and can include other fields). It also supports a response with just the token itself as the body. Further development work will need to be done to allow other resposne forms or other response fields.

Note

Users must exist in both Traffic Ops as well as in the OAuth provider’s system. The user’s rights are defined by the Role assigned to the user.

To configure OAuth login:

• Set up authentication with a third party OAuth provider.

• Update /opt/traffic_portal/public/traffic_portal_properties.json and ensure the following properties are set up correctly:

  Table 70 OAuth Configuration Property Definitions In traffic_portal_properties.json

  Name	Type	Description
  enabled	boolean	Allow OAuth SSO login
  oAuthUrl	string	URL to your OAuth provider
  redirectUriParameterOverride	string	Query parameter override if the oAuth provider requires a different key for the redirect_uri parameter, defaults to redirect_uri
  clientId	string	Client id registered with OAuth provider, passed in with client_id parameter
  oAuthCodeTokenUrl	string	URL to your OAuth provider’s endpoint for exchanging the code (from oAuthUrl) for a token

  #83 Example OAuth Configuration Properties In traffic_portal_properties.json

  {
      "oAuth": {
          "_comment": "Opt-in OAuth properties for SSO login. See http://traffic-control-cdn.readthedocs.io/en/release-4.0.0/admin/quick_howto/oauth_login.html for more details. redirectUriParameterOverride defaults to redirect_uri if left blank.",
          "enabled": true,
          "oAuthUrl": "example.oauth.com",
          "redirectUriParameterOverride": "",
          "clientId": "",
          "oAuthCodeTokenUrl": "example.oauth.com/oauth/token"
      }
  }
  

• Update /opt/traffic_ops/app/conf/cdn.conf property traffic_ops_golang.whitelisted_oauth_urls to contain all allowed domains for the JSON key set (Use * for wildcard):

  Table 71 OAuth Configuration Property Definitions In cdn.conf

  Name	Type	Description
  whitelisted_oauth_urls	Array of strings	List of whitelisted URLs for the JSON public key set returned by OAuth provider. Can contain * wildcards.
  oauth_client_secret	string	Client secret registered with OAuth provider to verify client, passed in with client_secret parameter

  #84 Example OAuth Configuration Properties In cdn.conf

  {
      "traffic_ops_golang": {
          "whitelisted_oauth_urls": [
              "oauth.example.com",
              "*.example.com"
          ],
          "oauth_client_secret": "secret"
      }
  }