README.md

How to work with the authorization.go middleware

I wanted to make sure no one gets slowed down in their PRs because of the introduction of authorization.go. It has been added to all the services and all HTTP endpoints are affected. Here is how to get around that.

The current impl of authorization.go is algorithm-agnostic regarding the verification. The gateway or sidecar proxy (Envoy/Istio) will handle the verification.

This endpoint has only two purposes (for now):

• expose token claims (userID and worskspaceID) via GetClaims(),
• check that ?workspace_id=someid matches the token's {"aud": "your-workspace-id"}

Content of this document:

• How to work with the authorization.go middleware
  • How does OAuth 2 works in this application
  • Create a JWT token manually for testing purposes
    • Step 1: Create a fake JWT token with the "aud":"workspaceid" field
    • Step 2: Add the Authorization header to your requests
    • Step 3: Add the query string ?workspace_id= in your request's URL
    • Examples of requests with curl and httpie
    • Important: how to fetch the token's workspaceID for using it in business logic

How does OAuth 2 works in this application

We chose to use the Client credentials grant. It is a 3-legs oauth flow: the end-user, the token provider and our application. We have two sides here:

Step 1 (scheme: Client Credential Grant):

• Resource Owner is the end-user with his password and email.
• Client is the dna-me service (confidential client using clientID and clientSecret).
• Authorization Server is Auth0.
• Resource Server is ???

Step 2 (scheme: ???):

• Resource Owner is the end-user with his password and email.
• Client (public client) is the end-user's browser or CLI.
• Authorization Server is dna-me with POST /oauth/token.
• Resource Server is the DNA HTTP API which holds the end-users' protected resources.

Flow:

+--------+    client_id        +---------+                   +----------+
|        |  & client_secret    |         |                   |          |
|        |  & password & email |         | password & email  |          |
|        |<--------------------|         |<------------------|          |
| Auth0  |                     | dna-me  |                   | Resource |
|        |-------------------->|         |-----------------> | Owner    |
|        |        token        |         |        token      |          |
|        |   with aud + sub    |         |   with aud   sub  |          |
|        |                     |         |                   |          |
+--------+                     +---------+                   +----------+

Create a JWT token manually for testing purposes

Step 1: Create a fake JWT token with the "aud":"workspaceid" field

Go to jwt.io and create manually a token that has in its payload the aud field. aud must contain a workspace ID (later, we could also have like an array). aud is defined in the Claims struct in authorization.go.

Example of a payload:

{
  "aud": "the-workspace-id-here"
}

Step 2: Add the Authorization header to your requests

In your request add the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ0aGUtd29ya3NwYWNlLWlkLWhlcmUifQ.CinWEubEWZGk26Yp8nYXzDAEujh5M27L0JA8m5UfwBY

Step 3: Add the query string ?workspace_id= in your request's URL

In your request you also need to add the ?workspace_id=the-workspace-id-here query string. ⚠️ this may change with time, do not use like r.URL.Queries().

Examples of requests with curl and httpie

export TOK="Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJhYmNkIn0.sOt2JK-rYn1JlSU53Uy2-E6D3OLunuGBsXvWbq8onI4"
curl -H "authorization: $TOK" "https://staging.dna.ori.co/api/alpha/deployments?workspace_id=abcd"
http "https://staging.dna.ori.co/api/alpha/deployments?workspace_id=abcd" authorization:$TOK

Note: in order to convert from curl to http I use curl2http (CLI or on the web) 👍

Important: how to fetch the token's workspaceID for using it in business logic

In order to get the workspace ID for business logic needs, please use:

claims, err := GetClaims(ctx)
log.Printf("%s", claims.WorkspaceID)

Some images stored in this comment (edit it to see)