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.
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.
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":
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":
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.
On your new API's page click the "Settings" tab:
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":
Scroll back up and click the API "Permissions" tab. Add the following permissions (corresponding to LRS resource scopes) as shown:
(For simplicity we will not be adding more specialized permissions such as lrs:statements/read/mine.)
Navigate to User Management > Roles:
Click "+ Create Role" and enter a Name and Description, then click "Create":
You will be navigated to the new role's page.
Click on the "Permissions" tab:
Click "Add Permissions" and select the API you created:
Select the lrs:all and lrs:admin permissions and click "Add Permissions":
Verify that the role you created now has the proper permissions:
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":
Enter an email address and password and click "Create":
Verify the user via email before proceeding.
Navigate to User Management > Users and find the user you want to administer SQL LRS. Click the "..." menu button and select "Assign Roles":
Select the LRS Admin role you created and click "Assign":
Your user account is now prepared to administer SQL LRS.
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":
Give it a name, select the application type "Single Page Web Applications" and click "Create":
You will be navigated to the page for the new application.
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":
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:
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.
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.
Navigate to http://localhost:8080 and click "OIDC LOGIN":
You should see a Login box. Log in with the user to whom you granted the LRS Admin role:
You will be presented with an "Authorize App" box, click the check mark:
If you have completed the above steps correctly, you will be redirected to the SQL LRS Admin console:
If you are not able to log in or receive an error, please let us know in a GitHub issue.