Oauth 2.0 Integration Guide

Register Your OAuth Application

Work with your Nexus system administrator to register your application. NOTE: If you are on a local development instance of Nexus, you can make yourself the SysAdmin by setting the SUPERUSER_EMAIL environment variable to your registered okta email address. As a system administrator, you can access the Site Mangement page by clicking the gear icon in the lower left of the application window:

You may then register new applications under “Oauth Applications” (middle tab):

When registering your application, you’ll need to provide:

• Application Name: A name or alias for your application
• Redirect URI: The callback URL where users will be redirected after authorization (e.g., https://yourapp.com/oauth/callback)

Additionally, you may want to provide these optional parameters:

• Description: Additional description of your application and what it does
• Base URL: The URL for your application. For DeepLynx Ecosystem developers, this can be used to aid in a smooth UI experience when transitioning between apps without necessitating environment variables for these apps’ URLs.
• Owner Email: The email address of the application developer or point of contact, in case any issues with the registered application arise

After registration, you will receive (from the System Administrator):

• Client ID: A public identifier for your application
• Client Secret: A confidential secret for authenticating your application

Critical: Store your Client Secret securely. Never expose it in client-side code, version control, or public repositories. Use environment variables or a secrets management service.

Initiate the Authorization flow

When a user wants to connect your application to Nexus, redirect them to the Nexus authorization endpoint.

Authorization Endpoint

GET {frontendUrl}/api/oauth/authorize

Required parameters

** Example Authorization URL **

Note that this example uses a client-side /login endpoint to trigger the Oauth handshake. This is not required, but redirecting to the /oauth/authorize is a requirement.

import secrets
from urllib.parse import urlencode
from flask import Flask, redirect
 
app = Flask(__name__)
 
@app.route('/login')
def login():
    state = secrets.token_urlsafe(32)
 
    # Build authorization URL
    params = {
        'client_id' = 'stored_client_id_123',
        'redirect_uri' = 'https://yourapp.com/oauth/callback',
        'state' = state
    }
 
    auth_url = f"https://nexus.example.com/api/oauth/authorize?{urlencode(params)}"
 
    return redirect(auth_url)

** What happens next **

1. The user is redirected to Nexus and prompted to sign in (if not already authenticated)
2. Nexus validates your Client ID and Redirect URI
3. Nexus redirects back to your callback URL with an authorization code

Extract Code and State from the Callback Endpoint

Create an endpoint in your application to receive the authorization code and exchange it for an access token.

** Callback Parameters **

When Nexus redirects back to your application, the URL will include:

** Example Callback Handler **

from flask import Flask, request, session, redirect
import requests
 
app = Flask(__name__)
 
@app.route('/oauth/callback')
def oauth_callback():
    # Extract parameters from callback URL
    code = request.args.get('code')
    state = request.args.get('state')
 
    # Any additional validation should occur here, such as
    # comparing state or checking for errors from Nexus.
 
    # Proceed to token exchange...

Exchange Code for Access Tokens

After validating the callback, exchange the authorization code for an access token.

** Token Exchange Endpoint **

NOTE: The /exchange endpoint uses v1 in the route due to being a backend route. /authorize does not use v1 because it is a frontend proxy endpoint. Lack of attention to this difference will likely result in errors.

POST {backendUrl}/api/v1/oauth/exchange

** Required Parameters **

** Example Token Exchange **

def exchange_code_for_token(code, state):
    token_url = 'https://nexus.example.com/api/v1/oauth/exchange'
 
    params = {
        'code': code,
        'state': state,
        'client_id': 'stored_client_id_123',
        'client_secret': 'stored_client_secret_456',
        'redirect_uri': 'https://yourapp.com/oauth/callback',
        'state': state,
        'expiration': 480 # 8 hours
    }
 
    response = requests.post(token_url, params=params)
    token_data = response.json()
    return token_data

** Successful Response **

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 28800,
  "state": "abc123..."
}

The expires_in value is in seconds (e.g., 288000 seconds = 8 hours).

Store Tokens securely

Proper token storage is critical for security. Store tokens on your backend server, never in client-side code. Encrypt tokens at rest in your database, and use HTTPS for all communications. It is also recommended that you implement token expiration checking and/or some sort of token refresh mechanism. Never store tokens in localStorage or cookies accessible to JavaScript. Never log tokens in plaintext nor commit them to version control.

Make Authenticated API Requests

Now that you have your access token, you can include it in the Authorization header of all API requests to Nexus.

def get_nexus_api(token, endpoint):
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
 
    response = requests.get(endpoint, headers=headers)
 
    return response.json()