This repo is proof-of-concept example of the proposed Identity Assertion Authorization Grant flow. This flow is a subset of the Token Exchange grant which allows identity assertions received by a client via SSO to be exchanged with a trusted Identity Provider for an id-jag token. Such a token can then be exchanged for an access token with the resource authorization server. For for information, watch the explainer video here.
To demonstrate the usage of this flow, this repo currently contains two applications: Wiki0 and Todo0.
When links to Todo0 tasks are pasted into a Wiki0 page, will unfurl and show task details automatically.
Note
When running locally, you must use a domain stored in the local database.
You should use the email bob@tables.fake to login to both applications, and this will initiate the login flow using the IDP information configured.
Steps:
- Login to Todo0
- Create a task in Todo0
- Copy the link to the task by clicking the "#"
- Login to Wiki0
- Create a new page
- Edit the page by pasting in the link to the Todo0 task
- See the unfurled task populate! (Example below)
This application runs locally using VSCode Dev Containers. If you cannot use VSCode, you can follow the instructions here.
At the project root, copy over the default files into .env files:
Note
You can run this application in either SAML or OIDC mode. In SAML mode, the Wiki0 authorization server will use SAML to SSO to the Idp as opposed to OIDC.
cp todo0/.env.default todo0/.env &&
cp wiki0/.env.default wiki0/.env &&
cp authorization-server/.env.wiki.default authorization-server/.env.wiki &&
cp authorization-server/.env.todo.default authorization-server/.env.todo
You must specify the following the issuer and client id in both your .env.todo & .env.wiki files to hook up the authorization server to your IDP:
CUSTOMER1_AUTH_ISSUER="<FILL IN>"
CUSTOMER1_CLIENT_ID="<FILL IN>"
For .env.wiki you must also specify your SAML configuraiton:
USE_SAML_SSO="true"
CUSTOMER1_SAML_ENTRY_POINT="<FILL IN>"
CUSTOMER1_SAML_ISSUER="<FILL IN>"
CUSTOMER1_SAML_CERTIFICATE="<FILL IN>"
Activate Dev Containers by:
- Typing
cmd+shift+P - Searching for "Dev Containers: Open Folder In Container"
- Navigating to the folder where the repo was cloned (e.g.
~/gitpublic/id-assertion-authz-node-example)
This will automatically begin installing dependencies in a terminal window in VSCode.
If running the app for the first time, seed the database to get your db in a baseline state:
yarn resetdb
Open a new terminal window within VSCode for below commands to run each application and its respective authorization server. Then, you may open the "PORTS" tab and click on the mapped "Forwarded Address" to open the app in your browser.
yarn dev:wiki
Running at http://localhost:3000/
yarn auth:wiki
Running at http://localhost:5000/
yarn dev:todo
Running at http://localhost:3001/
yarn auth:todo
Running at http://localhost:5001/
Stop the running node processes in the terminal, and stop the VSCode Dev Container or stop the container in Docker Desktop.
Alternative option for users who want to run this application locally without using VSCode Dev Containers.
Instructions
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm install-latest-npm
Yarn
npm install --global yarn
Follow the section Configuration
This install dependencies at the root and in the authorization sever, builds a local dependency package, and runs the initial DB schema migration.
yarn install && yarn postinstall
If running the app for the first time, seed the database to get your db in a baseline state:
yarn resetdb
First, standup Redis and MariaDB containers in a terminal window:
cd local-development
docker-compose up
Then, follow the section Running Locally
To stop the application, stop all running node processes using Ctrl + C and run:
cd local-development
docker-compose down
If you have any trouble, try re-authenticating to both applications by signing out and signing in again.
Access the mysql database directly with the following:
mariadb -u root --password=avocado -P 3306
Run the following after making schema changes to a schema.prisma file
Make sure to replace the content in <>.
export WIKI_DATABASE_URL=<DB_URL>
export TODO_DATABASE_URL=<DB_URL>
yarn dlx prisma migrate dev --name <some nice description of the changes you made> --schema <project>/prisma/schema.prisma
Remove all Redis keys with a given prefix
# PREFIX could be, for example, "todo0:"
redis-cli --scan --pattern "<PREFIX>" | xargs redis-cli del
This section outlines the steps needed to implement ID Assertion Authorization Grant in your existing application. There are three actors in this flow, the Identity Provider (IdP), the Requesting Application, and the Resource application.
-
The Identity Provider issues
ID-JAGtokens, and is the SSO provider for the Requesting and Resource apps for a given user. -
The Requesting Application is the Client application which will make the token exchange request to the IdP, ultimately requesting protected resource access from the Resource Server.
-
The Resource Application is the application which owns the protected resources and must issue access tokens to the Requesting Application using the flow.
You app can support this flow as a Requesting App, a Resource App, or both! We recommend integrating in only on way to get started. The section will also cover best practices based on the architecture of the given apps.
The Requesting App is the application that is requesting or querying objects or pulling data from another application. This section describes the specific steps to build the ID Assertion Authorization Grant into the application. The Requesting App must make a separate request to IdP for an ID-JAG token for each unique resource the user wants to access. To prevent performance issues, follow these best practices:
Tip
Checkout the Debug Console in the App for detailed views of the requests!
-
Configure SSO with an IdP which supports this flow.
-
After the Login SSO flow for a user, store the
id_tokenor therefresh_tokenreturned from the IdP. These are needed to make the token exchange request. (If theid_tokenexpires before you want to make the exchange, use therefresh_tokento receive a newid_token.) -
When you want to load a resource for a user in your application logic, make a token exchange request to the IdP within the lifetime of the
id_token. Follow this code example, and/or see the specifics of the request in Section 5 of the spec. -
Using the result of the exchange, make an
access_tokenrequest to the authorization server. Follow this code example, and/or see the specifics of the request in Section 6 of the spec. -
Store and use the
access_tokenas your normally would with the 3rd party resource server.
- Do not add to login flow. It is not necessary to preload all the JAG tokens, so it is not necessary to mint all of the possible JAG tokens at the time of login. The side effects can be extended login times for users.
- Only request when needed. JAG tokens should be requested at the last responsible moment. JAG tokens are not meant to be long lived. Loading does not need to be bulk loaded and optimized. Trying to optimize the requests for multiple JAG tokens can result in poor performance at scale.
- Do not store JAG Tokens. Store ID, Access and Refresh Tokens. JAGs are really short lived. As mentioned earlier, JAGs are passed from Requesting Apps to Resource Apps to exchange for an Access Token to access the Resource App. The Access Token is the valuable artifact to be stored and protected. The JAG token is effectively useless once exchanged, so it should be discarded.
The Resource App is the application that owns protected resources normally accessed via OAuth2.0 by Requesting App users. This section describes the specific steps to support the ID Assertion Authorization Grant into the application. The Resource App is responsible for validating ID-JAG tokens before issuing OAuth access_tokens as it normally would.
Tip
Checkout the Debug Console in the App for detailed views of the requests!
- Configure SSO with an IdP which supports this flow.
- Modify your Authorization Server logic accept these requests at your OAuth2.0 token endpoint. Seethe specifics of the incoming request in Section 6 of the spec.
- Validate the
ID-JAGtokens properly before issuing anaccess_tokenas your normally would. Ensure all validations your authorization makes in regular OAuth2.0 flows also apply to this exhcange when evaluating user atuhorization, such as scope validation. Follow this code example, and/or see the specifics of the processing rules in Section 6.1 of the spec. - Respond with an access token, as outlined in Section 6.1 of the spec.