Authentication - HearstCorp/rover-wiki GitHub Wiki

OpenId Authentication

Authorization Code Flow (redirect to Doorman for confirmation)

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
email 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