OpenID Connect Documentation

An implementation of OpenID Connect 1.0 (specs)

GET /oidc/authorize

Authorization Endpoint (specs)

  1. Query parameters
    Parameter name Required? Details
    Parameter name Required? Details
    response_type
    • must have value "code"
    client_id
    • client id provided by Ancestry
    redirect_uri
    • properly formed uri
    • must be included in list of registered uris for client_id
    scope
    • must have value "openid"
    prompt
    • must have value "none" to have any effect
    • if prompt=none then Ancestry will not display any interface pages
    • if the end user does not need to take action on Ancestry then a standard success redirect will occur
    • if the end user needs to take action on Ancestry then an error will be returned to redirect_uri indicating what action needs to be taken
    • possible errors: login_required, interaction_required
    • possible interactions: mfa_enable, password_entry
    state
    • this value will be passed-through untouched to redirect_uri
    nonce
    • this value will be passed-through untouched to redirect_uri
  2. Response
    Status HTTP Status Details
    Status HTTP Status Details
    Success 302 Found
    • Redirect to redirect_uri with a query string code={authorization code} and state/nonce parameters if included in request
    Error (with valid redirect_uri) 302 Found
    • Redirect to redirect_uri with query params error and error_description
    Error (with invalid redirect_uri) 200 OK
    • Error page
Example request 

GET https://www.ancestry.com/sso/oidc/authorize?
	response_type=code
	&scope=openid%20profile%20email
	&client_id=s6BhdRkqt3
	&state=af0ifjsldkj
	&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb HTTP/1.1
Example response 

HTTP/1.1 302 Found
Location: https://client.example.org/cb?
	code=SplxlOBeZQQYbYS6WxSbIA
	&state=af0ifjsldkj

POST /oidc/token

Token Endpoint (specs)

  1. Request Headers
    Header Required? Details
    Header Required? Details
    Content-Type
    • application/x-www-form-urlencoded
    Authorization
    • "Basic " + Base64Encode(client_id:client_secret)
    • Example value: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
  2. Form parameters
    Parameter name Required? Details
    Parameter name Required? Details
    grant_type
    • "authorization_code"
    code
    • authorization code received in query string of response to authorize request
    redirect_uri
    • the same redirect_uri that was used to generate the code
  3. Response status
    Status HTTP Status Details
    Status HTTP Status Details
    Success 200 OK
    • Body that includes an ID Token and an Access Token
    Error 400 Bad Request
    • Body will include an error and error_description
Example request 

POST https://www.ancestry.com/sso/oidc/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
Example response 

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
	"access_token": "SlAV32hkKG",
	"token_type": "Bearer",
	"expires_in": 3600,
	"refresh_token": "8xLOxBtZp8",
	"refresh_expires_in": "2592000",
	"id_token": "eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso"
}

POST /oidc/token

Refresh Request (specs)

  1. Request Headers
    Header Required? Details
    Header Required? Details
    Content-Type
    • application/x-www-form-urlencoded
    Authorization
    • "Basic " + Base64Encode(client_id:client_secret)
    • Example value: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
  2. Form parameters
    Parameter name Required? Details
    Parameter name Required? Details
    grant_type
    • "refresh_token"
    refresh_token
    • refresh_token received during authorization
    scope
    • desired scope(s)
    • space delimited
  3. Response status
    Status HTTP Status Details
    Status HTTP Status Details
    Success 200 OK
    • Body that includes an Access Token and potentially an ID Token
    Error 400 Bad Request
    • Body will include an error and error_description
Example request 

POST https://www.ancestry.com/sso/oidc/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

grant_type=refresh_token
&refresh_token=8xLOxBtZp8
&scope=openid%20profile
Example response 

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
	"access_token": "TlBN45jURg",
	"token_type": "Bearer",
	"refresh_token": "9yNOxJtZa5",
	"expires_in": 3600
}

GET /oidc/prompt

Prompt Endpoint

  1. Request Headers
    Header Required? Details
    Header Required? Details
    Origin
    • This value will be returned in the Access-Control-Allow-Origin header if valid
    • The value is considered valid if it matches the domain of a registered redirect_uri for provided client_id
    • Example value: https://client.example.org
  2. Query params
    Parameter name Required? Details
    Parameter name Required? Details
    client_id
    • client id provided by Ancestry
  3. Response status
    Status HTTP Status Details
    Status HTTP Status Details
    Success 200 OK
    • "status" property
      • "none" - user needs no interaction to complete authorize step
      • "login_required" - user needs to sign in to Ancestry
      • "interaction_required" - this will be accompanied by an "interaction" property
    • "interaction" property (if "status" is "interaction_required")
      • "mfa_enable" - user needs to enable multi-factor authentication
      • "password_entry" - user needs to re-enter password on Ancestry
    Authorization error 401 Unauthorized
    • Body will include an error and error_description
Example request 

GET https://www.ancestry.com/sso/oidc/prompt?client_id=s6BhdRkqt3 HTTP/1.1
Example response 

HTTP/1.1 200 OK
Content-Type: application/json

{
	"status": "none"
}