Authentication - HearstCorp/rover-wiki GitHub Wiki
OpenId Authentication
Authorization Code Flow (redirect to Doorman for confirmation)
- State Token
- Code Authentication
- Confirm State Token
- Token Authentication
- Obtain User Information
- Save State in Session
- Update Token Using Refresh
Email/Password Flow (stay on current site, no confirmation)
State Token
Must create/send a state token from your code to verify the user is making the request and it isn't a malicious attack. This is a good place to put any redirection url.
Example
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
Code Authentication
Name | Type | Description | Required |
---|---|---|---|
client_id | String | The Client ID from Doorman admin | yes |
response_type | String | The response_type from Doorman admin | yes |
scope | String | Must at least contain openid , could also contain a OpenID Scope from Doorman |
yes |
redirect_uri | String | URL for redirecting to, must match what's in Doorman admin. | yes |
state | String | State token | yes |
Example
GET https://doorman.hearst.io/openid/authorize?
client_id=12345678&
response_type=code&
scope=openid%20email%20roles&
redirect_uri=https://your-website.com/code&
state=security_token%3D138r5719ru3e1%26url%3Dhttps://oauth2-login-demo.example.com/myHome
Confirm State
The response will be sent to your redirect_uri, it's up to you to confirm that the state matches what's in the user's session, and extract any redirect url.
Token Authentication
Name | Type | Description | Required |
---|---|---|---|
code | String | The authorization code from authorize request. | code flow |
client_id | String | The Client ID from Doorman admin | yes |
client_secret | String | The Client Secret from Doorman admin | If not sending sig |
redirect_uri | String | URL for redirecting to, should match what's in Doorman admin. | code flow |
grant_type | String | authorization_code or password |
yes |
sig | String | For password grant_type, you can send client_id and sig just as you would in Client Authentication |
no |
timestamp | String | Timestamp used to generate sig | when using sig |
String | The email address of the user to login | password flow |
|
password | String | The password of the user to login | password flow |
Code Flow Example
POST /openid/token HTTP/1.1
Host: doorman.hearst.io
Content-Type: application/x-www-form-urlencoded
code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=12345678&
client_secret={client_secret}&
redirect_uri=https://your-website.com/code&
grant_type=authorization_code
Password Flow Example
POST /openid/token HTTP/1.1
Host: doorman.hearst.io
Content-Type: application/x-www-form-urlencoded
client_id=12345678&
sig={sha256(client_id+client_secret+timestamp)}
timestamp=1441027325
[email protected]
password=password
grant_type=password
Obtain User Information
This can be initially retrieved from the results of token authentication above (it returns a base64 encoded JSON object which contains the userinfo), but you can also call the endpoint by hand by passin in the access token you previously received.
Example call:
POST /openid/userinfo/ HTTP/1.1
Host: doorman.hearst.io
Authorization: Bearer [ACCESS_TOKEN]
Save State in Session
After user authentication you can save any user info locally that you need in the session, as well as the token.
Update Token Using Refresh
To get a new token for the user once it expires you should call the
Token Authentication Endpoint and set the
grant_type
to refresh_token
and pass a refresh_token
that you
received in your original call to the token endpoint (instead of passing
a code)
Example call:
POST /openid/token HTTP/1.1
Host: doorman.hearst.io
Content-Type: application/x-www-form-urlencoded
refresh_token=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=12345678&
client_secret={client_secret}&
redirect_uri=https://your-website.com/code&
grant_type=refresh_token
OIDC Scopes (Doorman specific)
Name | Description |
---|---|
user | Returns the data from the person's user object |
profiles | Returns a list of each of the users's site profiles |
roles | Returns a list of the roles the user has on each site |
Client Authentication
Name | Type | Description | Required |
---|---|---|---|
client_id | String | The Client ID from Doorman admin | yes |
sig | Hexadecimal String | A concatenation of the client id, secret, and a utc timestamp which have been sha256 hashed. | yes |
timestamp | Timestamp | The timestamp used to generate the sig | yes |
Example query parameter usage:
client_id = "1h43tj2g872jj428gj2"
client_secret = "supersecret"
# 1441027325
now = int(time.mktime(datetime.utcnow().timetuple()))
# bfec0eee6fd6bb648a028fbec5ee18c3bd1f3015
sig = hashlib.sha256("%s%s%s" % (client_id, client_secret, now)).hexdigest()
# '/v1/people?client_id=1h43tj2g872jj428gj2&sig=bfec0eee6fd6bb648a028fbec5ee18c3bd1f3015
response = self.client.get('/v1/people', {'client_id': client_id, 'sig': sig, 'timestamp': now})
Example header usage:
client_id = "1h43tj2g872jj428gj2"
client_secret = "supersecret"
# 1441027325
now = int(time.mktime(datetime.utcnow().timetuple()))
# bfec0eee6fd6bb648a028fbec5ee18c3bd1f3015
sig = hashlib.sha256("%s%s%s" % (client_id, client_secret,
now)).hexdigest()
GET /v1/people HTTP/1.1
Host: doorman.hearst.io
Content-Type: application/json
Authorization: Doorman-SHA256 Credential=1h43tj2g872jj428gj2
Signature: bfec0eee6fd6bb648a028fbec5ee18c3bd1f3015
Timestamp: 1441027325