Skip to content

Latest commit

 

History

History
213 lines (128 loc) · 9.17 KB

auth0.md

File metadata and controls

213 lines (128 loc) · 9.17 KB

<- Back to Index

Auth0 OIDC Setup Guide

This guide provides basic steps to authenticate and authorize SQL LRS (running locally on your machine) against the Auth0 Cloud Identity Provider. This guide is provided for example purposes only and may not produce an environment suitable for production usage.

Getting Started

Make an account on Auth0 and log in to the administrative console. Make sure you have the latest release of SQL LRS downloaded to your machine and unzipped. For this guide you'll need access to a command line and an application for editing JSON files.

Resource Server (API) Setup

Create an API

To enable token authentication to SQL LRS you'll need to configure Auth0 to use the LRS as an OAuth 2.0 Resource Server. To do this, log in to the Auth0 Dashboard and navigate to Applications > APIs. Click "+ Create API":

Auth0 APIs page

Give your API a descriptive Name like lrsql_api and set the API Identifier to http://localhost:8080 (the origin of the SQL LRS instance we will launch) then click "Create":

New API page

You will be redirected to the page for the new API. Note that the API Identifier you enter will be used for the Audience parameter later on.

Enable Role-Based Access Control

On your new API's page click the "Settings" tab:

API settings page

Now you'll need to enable Role-Based Access Control (RBAC). Scroll down to "RBAC Settings". Toggle on the switches for "Enable RBAC" and "Add Permissions in the Access Token" and click "Save":

API RBAC settings

Add Permissions (Scopes)

Scroll back up and click the API "Permissions" tab. Add the following permissions (corresponding to LRS resource scopes) as shown:

API permissions

(For simplicity we will not be adding more specialized permissions such as lrs:statements/read/mine.)

Role Setup

Add a Role

Navigate to User Management > Roles:

Roles list

Click "+ Create Role" and enter a Name and Description, then click "Create":

New role

You will be navigated to the new role's page.

Assign Permissions (Scopes)

Click on the "Permissions" tab:

Empty role permissions

Click "Add Permissions" and select the API you created:

Add permissions select API

Select the lrs:all and lrs:admin permissions and click "Add Permissions":

Add permissions select permissions

Verify that the role you created now has the proper permissions:

Verify role permissions

Create a User (Optional)

In the next section you'll assign the LRS Admin role you created to a user. If you don't already have a user you'd like to use, navigate to User Management > Users and click "+ Create User":

Empty users list

Enter an email address and password and click "Create":

New user form

Verify the user via email before proceeding.

Assign the Role to a User

Navigate to User Management > Users and find the user you want to administer SQL LRS. Click the "..." menu button and select "Assign Roles":

Assign roles

Select the LRS Admin role you created and click "Assign":

Assign role choose role

Assign role finish

Your user account is now prepared to administer SQL LRS.

LRS Admin Application Setup

Create an Application

Before you can launch and log in to SQL LRS with Auth0 you'll need to create an "Application" to represent the front end admin SPA. Navigate to Applications > Applications (sic) and click "+ Create Application":

Applications list

Give it a name, select the application type "Single Page Web Applications" and click "Create":

Create application

You will be navigated to the page for the new application.

Set a Callback URL

Click the "Settings" tab and scroll down to the "Application URIs" section. In the "Allowed Callback URLs" box enter http://localhost:8080/admin/index.html, scroll down and click "Save Changes":

Set callback URL

Get Client ID

Scroll up to the top of your Application's page and copy down your "Client ID". You'll need this to configure SQL LRS in the next step:

Get client id

SQL LRS Setup

Configure SQL LRS

In your SQL LRS directory add a file named lrsql.json in the config subdirectory with the following contents:

{
  "lrs": {
    "oidcScopePrefix": "lrs:"
  },
  "webserver": {
    "oidcIssuer": "https://<you>.auth0.com/",
    "oidcAudience": "http://localhost:8080",
    "oidcClientId": "<your client id>"
  }
}

Replace the hostname in oidcIssuer with your auth0 hostname. Replace oidcClientId with the Client ID you recorded in the previous section.

Run SQL LRS

From the root of the SQL LRS directory run:

./bin/run_sqlite_ephemeral.sh

This will launch an in-memory instance of SQL LRS that will not persist any data to disk. If SQL LRS starts successfully you should see something like the following:

10:01:51.885 [main] INFO  com.zaxxer.hikari.HikariDataSource - HikariPool-1 - Starting...
10:01:51.963 [main] INFO  com.zaxxer.hikari.pool.HikariPool - HikariPool-1 - Added connection org.sqlite.jdbc4.JDBC4Connection@36aeef57
10:01:51.977 [main] INFO  com.zaxxer.hikari.HikariDataSource - HikariPool-1 - Start completed.
10:01:51.978 [main] INFO  lrsql.system.database - Starting new connection for sqlite database...
10:01:52.001 [main] INFO  lrsql.sqlite.record - sqlite schema_version: 26
10:01:52.270 [main] INFO  lrsql.system.lrs - Starting new LRS
10:01:52.278 [main] WARN  lrsql.util.cert - No cert files found. Creating self-signed cert!
10:01:52.505 [main] INFO  org.eclipse.jetty.util.log - Logging initialized @15405ms to org.eclipse.jetty.util.log.Slf4jLog
10:01:52.665 [main] INFO  org.eclipse.jetty.server.Server - jetty-9.4.51.v20230217; built: 2023-02-17T08:19:37.309Z; git: b45c405e4544384de066f814ed42ae3dceacdd49; jvm 11.0.12+0
10:01:52.695 [main] INFO  o.e.j.server.handler.ContextHandler - Started o.e.j.s.ServletContextHandler@462ffc16{/,null,AVAILABLE}
10:01:52.750 [main] INFO  o.e.jetty.server.AbstractConnector - Started ServerConnector@4bbb35b5{HTTP/1.1, (http/1.1, h2c)}{0.0.0.0:8080}
10:01:52.754 [main] INFO  o.e.jetty.util.ssl.SslContextFactory - x509=X509@5d1c9c94(lrsql_keystore,h=[com.yetanalytics.lrsql],a=[],w=[]) for Server@23a258e7[provider=null,keyStore=null,trustStore=null]
10:01:52.847 [main] INFO  o.e.jetty.server.AbstractConnector - Started ServerConnector@3abf8109{SSL, (ssl, alpn, h2, http/1.1)}{0.0.0.0:8443}
10:01:52.847 [main] INFO  org.eclipse.jetty.server.Server - Started @15747ms
10:01:52.847 [main] INFO  lrsql.system.webserver - Starting new webserver at host 0.0.0.0, HTTP port 8080, and SSL port 8443
10:01:52.847 [main] INFO  lrsql.system.webserver -
   __  ______     _   _
|\ \ \ \     |   | | | |     _        _               _       _
| \ \_\ \    |   | |_| |    | |_    / _ \            | |_   _| |_ _
| /   __ \   |    \   / ____| __|  |  _  |  _    ____| | |_| |  _|_|  ___   ___
|/ /\ \ \ \  |     | | | / /| |    | | | |/ _ \ / /_ | |\   /| |  _ / __/  / __|
  /  \ \ \ \ |     | | |  /_| |_   | | | | | | | |_| | | | | | |_| | |___  _| |
 /____\ \_\ \|     |_| |____|\__|  |_| |_|_| |_|\__|_|_| |_|  \__|_|\____/___/
        _______    _______    _            _          _______    _______
       |  _____|  |  ___  |  | |          | |        |  ___  |  |  _____|
       | |_____   | |   | |  | |          | |        | |___| |  | |_____
       |_____  |  | |   | |  | |          | |        |   ____|  |_____  |
        _____| |  | |__ | |  | |_____     | |_____   | |\  \     _____| |
       |_______|  |_____\_\  |_______|    |_______|  |_|  \__\  |_______|
                        (c) 2021-2024 Yet Analytics Inc.

Log in via Auth0

Navigate to http://localhost:8080 and click "OIDC LOGIN":

OIDC login button

You should see a Login box. Log in with the user to whom you granted the LRS Admin role:

OIDC login box

You will be presented with an "Authorize App" box, click the check mark:

OIDC grant box

If you have completed the above steps correctly, you will be redirected to the SQL LRS Admin console:

OIDC logged in

If you are not able to log in or receive an error, please let us know in a GitHub issue.

<- Back to Index