OAuth Configuration

From version ROB-EX Scheduler v7.6 the use of OAuth identity providers is supported.

*On the initial release OAuth login is supported for Web Clients only – Desktop Client login using OAuth will be supported in the months following the 7.6 release.

When the ROB-EX Scheduler Multiuser Server is correcly configured for OAuth login, the login form will contain additional buttons for the different configured OAuth clients, like shown on this picture.

The OAuth authorization code flow is used to authenticate the user with an external OAuth provider.

The ROB-EX Scheduler Multiuser Server is based on Spring Security meaning, a lot of the information regarding the OAuth configuration can be found in the Spring Security OAuth pages:

• https://docs.spring.io/spring-security/reference/servlet/oauth2/login/core.html
  

Main steps to configure OAuth authentication

!The ROB-EX Scheduler Multiuser Server must use ssl encryption (https) for most OAuth providers to allow redirect! See Securing network traffic – SSL for information on how-to enable SSL certificates for ROB-EX Scheduler Multiuser Server.

In your OAuth provider

1. setup an OAuth client with the authorization code flow enabled.
2. Add redirect urls to point to the ROB-EX Scheduler client endpoint of the server installation
   - eg. https://<robex_server_host_and_port>/login/oauth2/code/<client_name>
3. Collect the issuer uri, client id and client credentials from the newly created OAuth client

In ROB-EX Scheduler

1. Configure the ROB-EX Scheduler Multiuser Server through the application.yaml configuration file to authenticate against the OAuth client
2. Setup OAuth role mapping or configure site access through Admin UI

Relevant OAuth configuration settings in application.yml

!Exact use of upper and lower casing, underscores etc. matters in all aspects of the OAuth configuration

# Spring configuration changes
spring:
  security:
    oauth2:
       resourceserver: # Configure resource server that uses the oauth token
           jwt:
               issuer-uri: <oauth issuer uri>
       client: # Oauth client configuration section
           provider: # Oauth provider configuration section
             my-oauth-provider: # Name of the provider - used below to identify which provider the client registration uses
               issuer-uri: <oauth issuer uri> 
               user-name-attribute: email # User name attribute used to map a oauth claim to the username in Rob-Ex
           registration:
             my-oauth-client: # Specific OAuth client registration
               provider: my-oauth-provider # Link to provider above
               client-name: My OAuth provider name # Name used for Login button in Rob-Ex
               client-id: <oauth-client-id>
               client-secret: <oauth client secret>
               scope: # Scopes requested from the OAuth client
                - openid # needed for OAuth
                - profile # needed for OAuth
                - email # needed for OAuth
                - Robex_User # Optional scopes below used to map to roles in Rob-Ex
                - Robex_Admin
                - Robex_Planner
                - Robex_Viewer

# Robex configuration changes
robex:
  auth:
     internal:
        enabled: true # Enable "internal user authentication" - the default user authentication in Rob-Ex
     oauth:
        enabled: true # Enable OAuth user authentication - configure above
        groupsClaim: groups # Optional claim name of groups claim used to map against external role mappings in Rob-Ex

Role mapping

A newly install of ROB-EX Scheduler Multiuser Server will have a set of default predefined external role mappings:

Robex_Admin

Grants the “All site admin role”

Robex_Planner

Grants the “All site planner role”

Robex_Viewer

Grants the “All site viewer role”

More mappings can be added through the Admin UI in Configure->Security rules by adding a Security rule of type AD Mapping. As “AD Group/User” enter the Scope/Claim keyword.

To map OAuth users to roles in ROB-EX Scheduler there are two approaches:

1. Scope role mapping
2. Claim role mapping

Scope role mapping

In the OAuth client define which scopes should be available to ROB-EX Scheduler. That could be the predefined roles, eg. Robex_Admin, Robex_Viewer, Robex_Planner. Or any other scope you define.

When logging in with OAuth the server is set up to request all scopes for the user – if a user is only a viewer, the OAuth server will only return the Robex_Viewer scope.

After OAuth authentication the ROB-EX Scheduler Multiuser Server now checks all granted scopes from the user against external role mappings defined as Security rules.

If a scope matches an external role mapping, then the user is granted the defined role for the mapping.

Claim role mapping

When authenticating with OAuth, the OAuth server returns a set of claims, like name, email, etc. If the OAuth server is configured to return a claim with roles, the ROB-EX Scheduler Multiuser Server can extract the roles and match them against preconfigured external role mappings, like the scope mapping above.

Use the robex.auth.oauth.groupsClaim setting to control the claim with groups. The groups claim can be nested eg. “resource_access.roles” or just a root claim like “groups” . See below how to configure it.

# Robex configuration changes
robex:
  auth:
     internal:
        enabled: true # Enable "internal user authentication" - the default user authentication in Rob-Ex
     oauth:
        enabled: true # Enable OAuth user authentication - configure above
        groupsClaim: groups # Optional claim name of groups claim used to map against external role mappings in Rob-Ex

*The groups claim can be a comma seperated list

Using sample configuration files

A list of pre-made examples are available in the ganttServerG2\config_examples folder in the installation directory of ROB-EX Scheduler Multiuser Server. The easiest way to apply a setup for an OAuth provider is to use a feature of Spring Boot server, where multiple .yml configuration files are loaded on startup of the ROB-EX Scheduler Multiuser Server.

1. Copy the relevant example file from ganttServerG2\config_examples to the parent folder. As an example copy ganttServerG2\config_examples\application-azure.yml to ganttServerG2\application-azure.yml to add support for Azure AD OAuth authentication.
2. Make the necessary adjustments to the ganttServerG2\application-azure.yml file using e.g. Notepad++ or some other editor.
3. Edit the primary ganttServerG2\application.yml file, instructing additional profiles to be active (and thus loaded) during startup of ROB-EX Scheduler Multiuser Server. This is done by editing the spring.profiles.active setting, specifying a comma separated list of all active profiles (by default an existing sqlserver or sqlserverAD profile is typically also active!). Only specify the XXX part of the yml file application-XXX.yml. Again with Azure as the example, the resulting relevant application.yml config would read the following:

spring:
   profiles:
      active: sqlserver, azure

Remember to restart the ROB-EX Scheduler Multiuser Server service for any change to a .yml file to become active!

Troubleshooting

The following is a list of common problems we’ve been made aware of:

My config seems to be correct, but the rbx_srv_log.txt file contains errors like “Caused by: io.netty.resolver.dns.DnsNameResolverException: failed to send a query ‘6762’ via UDP. Caused by: Java.net.SocketException: Network is unreachable: sendto”

As a solution add the following startup parameter to the options part of the ROB-EX Scheduler Multiuser Server service: -Djava.net.preferIPv4Stack=true. Also see Server Service startup parameters.