Auth Specs (Old, Remove when ready)
Specification for the expected behaviour of Ego's Auth mechanisms. One of the things to keep in mind, is that Ego is both an Authorization Server and a Resource Server
Depending on whether or not the subject trying to authenticate is a user or a client application there are different flows to follow.
Note:
- If ego does not have a record of the user before hand, it will create a record on successful authentication
- User emails are the business key of the user. For now we only allow identity providers that verify ownership of primary email.
This flow assumes that a user, through the use of a User Agent (browser) will be making requests.
Diagram from the OAuth2.0 RFC:
+----------+
| Resource |
| Owner |
| |
+----------+
^
|
(B)
+----|-----+ Client Identifier +---------------+
| -+----(A)-- & Redirection URI ---->| |
| User- | | Authorization |
| Agent -+----(B)-- User authenticates --->| Server |
| | | |
| -+----(C)-- Authorization Code ---<| |
+-|----|---+ +---------------+
| | ^ v
(A) (C) | |
| | | |
^ v | |
+---------+ | |
| |>---(D)-- Authorization Code ---------' |
| Client | & Redirection URI |
| | |
| |<---(E)----- Access Token -------------------'
+---------+ (w/ Optional Refresh Token)
Ego supports this flow as the primary method for authenticating and providing authorization for users.
In order for ego to support having multiple client front ends use the authorization code flow, ego needs to have a mechanism for knowing what the final redirect URI should be.
Example of what should happen:
User A logs in from portal.superscience.gov using ego.superego.ca gets redirected back to portal.superscience.gov/someredirectionpath
User B logs in from analytics.bigbrains.on.ca using ego.superego.ca gets redirected back to analytics.bigbrains.on.ca/anotherredirectionpath
Sequence diagram for how this will work in ego:
Question: How does ego resolve the correct client redirect when coming back to the oauth/cb?authorizationcode= endpoint from the identity provider.
Answer: Ego creates a session to manage the authentication until it resolves back with the authorization code. On completion, the session cookie is used to look up the correct redirect to the corresponding client_id used in the original request.
The end result is that the user, through the user-agent can resolve the session for the authentication to obtain their authorization in the form of a JWT.
Example payload of a user JWT:
{
"iat": 1550161320,
"exp": 1550247720,
"sub": "4bbb67ae-6d41-4620-9b77-4f80e119810b",
"iss": "ego",
"aud": [],
"jti": "71212ef5-48c0-483f-82ea-c9d02e0b834a",
"context": {
"scope": [
"testpolicy.WRITE"
],
"user": {
"name": "[email protected]",
"email": "[email protected]",
"status": "Approved",
"firstName": "Foo",
"lastName": "Bar",
"createdAt": 1549486881327,
"lastLogin": 1550161320974,
"preferredLanguage": null,
"userType": "ADMIN",
"permissions": [
"testpolicy.WRITE"
]
}
},
"scope": [
"testpolicy.WRITE"
]
}The client credentials flow is a simple flow designed to allow for applications to obtain access tokens.
Diagram from the OAuth2.0 RFC:
+---------+ +---------------+
| | | |
| |>--(A)- Client Authentication --->| Authorization |
| Client | | Server |
| |<--(B)---- Access Token ---------<| |
| | | |
+---------+ +---------------+
Figure 6: Client Credentials Flow
This is the primary flow for authenticating and authorizing applications in Ego.
The end result is that the application is returned a JWT with which it can pass in the authorization header as a Bearer token for subsequent requests.
Example payload of an application JWT:
{
"iat": 1550590969,
"exp": 1550677369,
"sub": "0fb26924-37da-45ae-b212-80be975a5fd4",
"iss": "ego",
"aud": [
"some app"
],
"jti": "8fb26f94-63fb-43c6-85f2-788d5210c260",
"context": {
"application": {
"name": "some app",
"clientId": "abc123",
"redirectUri": "http://localhost:3501",
"description": "My application",
"status": "Approved",
"applicationType": "ADMIN"
}
}
}In order for Ego to be backwards compatible with the requirements of ICGC, it needs to be able to issue API Keys (Access Tokens) that can be used by other tools such as SONG and Score. They are meant to be used as Bearer tokens, however they are not JWTs.
The following endpoints are for these API Keys:
- POST /o/check_token
- DELETE /o/token
- GET /o/token
- POST /o/token
These endpoints are protected with Basic auth.
For a given application, with a clientId and clientSecret, to make a request to an endpoint requiring Basic Auth, it requires the following header:
Authorization: Basic <value> where <value> is the Base64 encoding of <clientId>:<clientSecret>
This functionality is deprecated and is coupled to the google and facebook SDKs. They should not be treated as proper OAuth2.0 implementations. Avoid its use.
The following endpoints allow for the exchange of a google or facebook identity token generated from their JS SDKs to an authenticated and authorized Ego JWT:
- GET /oauth/facebook/token
- GET /oauth/google/token
Assuming the UI and Ego are configured to use the same google or facebook application credentials, upon logging into either in the browser, the browser can than use these endpoints to login to Ego and obtain a JWT for the user.
Minimum required test coverage:
- Social Logins (OAuth2.0 SSO)
- User login with Google, obtains JWT
- User login with Facebook, obtains JWT
- User login with GitHub, obtains JWT
- User login with LinkedIn, obtains JWT
- Application Auth
- Application obtains JWT with client credentials flow
- API Keys
- Application uses Basic Auth to create API Key on behalf of user.
- Application uses Basic Auth to check API Key
- Application uses Basic Auth to revoke API Key
- Ego Authorization
- User logs in, is type
USER, gets 403 on Ego CRUD - User logs in, is type
ADMIN, able to get 200 on Ego CRUD - Application obtains JWT of type
CLIENT, gets 403 on Ego CRUD - Application obtains JWT of type
ADMIN, gets 200 on Ego CRUD
- User logs in, is type