Novulo OAuth2.0 configuration and usage

[m.gechev]

Novulo OAuth 2

OAuth2 for Novulo applications has been implemented and can be used to authenticate Novulo users from different contexts—be it normal usage of the Novulo application or requests against a web service in a Novulo application.

The implementation of the Novulo OAuth2 Authorization server follows the RFC for The OAuth 2.0 Authorization Framework.

---

Contact your primary contact for license details.

---

Supported Grant Types

The Novulo OAuth2 implementation supports the following grant types (for details, refer to the RFC link above):

• Authorization Code
• Implicit
• Password Credentials
• Client Credentials

OAuth 2.0 Endpoints

The OAuth 2.0 Authorization exposes 2 endpoints in the application in order to perfrom the User authorization and obtaining access token. These are:

• /oauth2/authorize ( /default.aspx would also work, given the needed OAuth2.0 Authorization request parameters are in the query)
• /oauth2/token - to obtain a token (to exchange Authorization code for token, or when using Password credentials/Client credentials flows, or when refreshing token)

For example, if this the base URL for you application

https://staging01.novulo.com/training01/default.aspx

Then the OAuth2 endpoints are at :

• https://staging01.novulo.com/training01/oauth2/authorize
• https://staging01.novulo.com/training01/oauth2/token

---

Requirements

To enable and use the Novulo OAuth2 implementation in your application, you need to meet the following requirements:

Application Requirements

Mandatory

Mandatory

1. Component: M9939 Novulo OAuth2 Authorization Server
2. Web Configuration: The following configuration must be added to your application’s web.config file.

Web Configuration Steps

1. If Novulo OAuth2 is your main identity provider:

• Set the key authentication to:

  Novulo.Plugins.OAuth2.AuthenticationProviders.OAuth2AuthenticationProvider,NovuloOAuth2
  

• Set a key with the name OAuth2AuthenticationProvider.identificationprovider to:

  Novulo.Framework.Controller.DefaultAuthenticationProvider, RightsSettings
  

  (or any other identification provider you wish to use after OAuth2).

2. If another identity provider precedes Novulo OAuth2:

• Update the value of xxxx.identificationprovider to:

  Novulo.Plugins.OAuth2.AuthenticationProviders.OAuth2AuthenticationProvider,NovuloOAuth2
  

• Set a key with the name OAuth2AuthenticationProvider.identificationprovider to:

  Novulo.Framework.Controller.DefaultAuthenticationProvider, RightsSettings
  

  (or any other identification provider you wish to use after OAuth2).

For more information about Authentication providers and the suggested order in which they should be you can refer to this article. You can set these webconfig settings via “Custom web config settings” in deployment or manually via SVN commit.

3. Your application needs to run in an Integrated IIS application pool. Under the system.webServer section of your web.config, inside the modules subsection, add the following module:

<add name="NovuloOAuth2HttpModule" type="Novulo.Plugins.OAuth2.NovuloOAuth2HttpModule, NovuloOAuth2" />

Optional

Optional

1. Component: If you have M9445 - Novulo User Locking and IP Blocking, update it to at least revision 29 to enable login restrictions in the OAuth2 context.
2. Component: If you have M8465 - Novulo Data and Processes for REST HV (configurable endpoints), update it to at least revision 227.
3. Component: If you have M9207 - Novulo TOTP Authentication in your application, you need at least revision >= 18 of the component as it provides a plugin change necessary to make the TOTP work with OAuth2.

Optional Web Configuration Items:

• If users are performing Authorization Code/Implicit flow with a user who is an SSO user (i.e., login happens in another application), you might end up with a HTTP 404.15 error (URL/query too long). This can be configured either on IIS level or via web.config. See docs
• This needs to be set in the application that is the SSO identity provider (i.e., if you click “Login with Novulo support”, you are redirected to NNetwork - Novulo. The application at NNetwork - Novulo needs the webconfig setting).
• Basically set the following in the configuration/system.webServer/security section (the numeric values are examples, they may be sufficient or not):

<requestFiltering>
    <requestLimits maxQueryString="2048" maxUrl="4096" />
</requestFiltering>

• OAuth2Configs.authorization_code_max_lifetime_minutes - Numeric value, specifies the maximum lifetime of an authorization code in minutes (not the final value, just a limit). Default from the plugin is 10 minutes.
• OAuth2Configs.access_token_max_lifetime_minutes - Numeric value, specifies the maximum lifetime of an access token in minutes (not the final value, just a limit). Default from the plugin is 60 minutes.
• OAuth2Configs.refresh_token_max_lifetime_days - Numeric value, specifies the maximum lifetime of a refresh token in days (not the final value, just a limit). Default from the plugin is 30 days.
• OAuth2Configs.rights_profiles_allowed_to_modify_tokens - String value, can contain multiple entries separated by ; (no spaces between values). Specifies the rights profile names that allow users to create/edit Token records. Default profiles are “Administration profile” and “Administrator”.

---

In-app Configuration and Records

OAuth 2.0 Client Related Configuration

When at least the mandatory requirements are done, you can now register the OAuth2 client with the Novulo Authorization server, which represents your client application.

In-app Configuration Steps:

1. In your Novulo application, go to All Apps -> Users -> OAuth 2.0 Clients.
2. Create a new OAuth 2.0 client.
3. This is what a filled-in client looks like:

Configuration Fields:

• Application Name: The display name for your non-Novulo application/HTTP client.
• Client Identifier: A unique string identifying the client (like a username).
• Client Secret: An invisible field (like a password for the Client Identifier). You will get one when you save your OAuth 2.0 client record, or you can regenerate a new one by clicking the button. It is displayed only once, so store it securely.
• Type: Confidential/public (refer to the RFC above for the difference between the two).
• User for Confidential Clients: Applicable only when the client is of type “confidential.” It defines the user who will be used for the create/modified by when the Client Authorization flow is used. Note that access in the application for this user is restricted by the linked user rights profile.
• Authorization Code Expiry Minutes: Default/max is 10 minutes (the lifespan of an authorization code in which the code can be exchanged for an access token).
• Access Token Expiry Minutes: Default/max is 60 minutes (the lifespan of an access token; after the specified value, a new access token needs to be obtained, either by using the refresh token (if issued) or by performing the authorization steps again).
• Issue Refresh Token: This checkbox sets whether a refresh token should be issued or not (only applicable for Access Tokens issued using the Authorization Code flow or the Password Credentials flow).
• Refresh Token Expiry Days: Default/max is 30 days (the lifespan of a refresh token, after which it becomes invalid and a new one needs to be issued).

Token record

The issued Authorization codes, Access tokens and Refresh tokens can be seen under All Apps -> Application Maintenance -> Users -> Tokens

For more information about the different token types and their usage, you can always refer to the RFC linked above, but in short:

Authorization code - a temporary credential (valid for up to 10 minutes), that is issued after a User granted authorization to the connecting client. This authorization code needs to be exchanged at the /oauth2/token endpoint for an actual access token

Access token - a temporary credential (valid for up to 1 hour), that the client application uses to Authenticate requests, on behalf of the user. This is what you use in the Authorization header with prefix Bearer .

Refresh token - an optional temporary credential (valid for up to 30 days). For the supported grant types ( Authorization code and Password credentials), a refresh token can be issued, that is returned in the same response as the Access token. Since the access token is valid for up to 1 hour, the refresh token can be used to obtain a new access token, without the need of any user interaction.

Only related to the currently logged in user Token records are visible.
Only users with Administration rights profiles have full access to (all) token records.

Users with non-administration rights profiles, see only their tokens. For example, this user has non-admin rights profile and sees the tokens issued only linked to this user:

Obtaining Authorization Code/Token

There are two ways to obtain an authorization code/token in Novulo OAuth2:

Redirect URL (for clients that expose a redirect URL):

If the connecting client application exposes a redirect URL (where the code and access token responses from the Authorization server are sent back), this URL needs to be registered as a redirection endpoint on the Novulo OAuth 2.0 client. Any request with an unknown redirect URL will be blocked and will not succeed.

No Redirect URL (Authorization Code/Access Token displayed directly):

Alternatively, if no redirect URL is provided with the initial request, the Authorization Code/Access Token will be displayed directly in the Novulo application after finishing the Authorization flow.

Example usage

Obtaining Access token using Authorization code flow for User with TOTP enabled

For this example I would be using Postman to obtain the Access token.

Here is the OAuth2 client configuration in postman:

• Note - the Scope parameter is mainly used for validation, it does not limit the access of the issued token. The access of the issued access token is determined by the User’s Novulo Rights profile

1. After configuring the OAuth2 client in postman, i click Get new access token button. This opens the novulo application with the Oauth parameters in the query:
   
   
2. On login, since I use TOTP enabled user, first I have to enter the OTP:
   
   
3. After successfully authenticating the Novulo Application, you will land on the Consent page. Here you should give (or deny) the request of the OAuth 2.0 client - if you allow it to impersonate you, using the Access token that will be issued:
   
   
4. If you Click deny, token will not be issued and that will be reported back to your HTTP client (or on the screen, if you didn’t provide redirect url). If you click Allow - authorization code is issued, which the HTTP client needs to exchange for access token (and optionally refresh token) at the /oauth2/token endpoint. After the request to the token endpoint - we get our access token, here is the raw request + response, that contains the access token, the number of seconds it is valid for, optionally the refresh token :
   
   

Using the obtained Access token to authenticate REST Endpoint request

After the steps above are performed, now the Access token can be used to perform HTTP requests to a Novulo REST Endpoint (or the Novulo Application itself). You should put the access token in the Authorization header of the request in the format “Bearer <access_token_here>”