Authorization Code Flow

Authorization Endpoints

The authorization code flow is used by server-based clients. Anvil Connect provides four endpoints that can be used to initiate authorization and obtain security tokens.

• /authorize
• /signin
• /signup
• /connect/:provider

Registered clients can choose among them according to their requirements. Each of the endpoints requires a set of valid OpenID Connect parameters:

• response_type determines the type of authorization flow
• redirect_uri is the client's callback endpoint
• client_id is the client's id
• scope specifies the scope of the authorization token that may be issued

/authorize

Use the /authorize endpoint to initiate authentication flows. Users that do not have an authenticated session with the authorization server will be redirected to /signin. HTTP GET and POST methods are supported at this endpoint.

GET

GET /authorize
  ?response_type=code
  &client_id=3ae09536-db18-4de8-a68d-6539459702f0
  &redirect_uri=http%3A%2F%2F127.0.0.1%2Fcallback
  &scope=openid+profile HTTP/1.1
Host: your.authorization.server

POST

POST /token HTTP/1.1
Host: your.authorization.server
  
response_type=code
&client_id=3ae09536-db18-4de8-a68d-6539459702f0
&redirect_uri=http%3A%2F%2F127.0.0.1%2Fcallback
&scope=openid+profile

/signin and /signup

Clients can also direct users to the /signin or /signup endpoint. Once a user has established an authenticated session by signing in or signing up, these endpoints will behave the same as /authorize.

GET /signin

GET /signin
  ?response_type=code
  &client_id=3ae09536-db18-4de8-a68d-6539459702f0
  &redirect_uri=http%3A%2F%2F127.0.0.1%2Fcallback
  &scope=openid+profile HTTP/1.1
Host: your.authorization.server

GET /signup

GET /signup
  ?response_type=code
  &client_id=3ae09536-db18-4de8-a68d-6539459702f0
  &redirect_uri=http%3A%2F%2F127.0.0.1%2Fcallback
  &scope=openid+profile HTTP/1.1
Host: your.authorization.server

/connect/:provider

A user that wishes to sign in via a third party provider or to connect a third party account to their existing account on the authorization server can be directed to the /connect/:provider endpoint. Supported third party providers must be configured in advance.

GET /connect/google
  ?response_type=code
  &client_id=3ae09536-db18-4de8-a68d-6539459702f0
  &redirect_uri=http%3A%2F%2F127.0.0.1%2Fcallback
  &scope=openid+profile HTTP/1.1
Host: your.authorization.server

HTTP/1.1 302 Moved Temporarily
location: https://accounts.google.com/o/oauth2/auth
  ?response_type=code
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A3000%2Fconnect%2Fgoogle%2Fcallback
  &scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.profile%20...
  &state=62caa29cd38f50327f62
  &client_id=875546373988.apps.googleusercontent.com

Third Party Authorization Callback

/connect/:provider/callback

This endpoint receives authorization results from third party providers and completes client authorization.

Obtaining Consent

After a user is authenticated, the authorization server may prompt the user for explicit consent before redirecting to the client's redirect_uri.

NOTE: With trusted clients, user consent is implied and the scope of authorization is predetermined.

HTTP/1.1 302 Moved Temporarily
location: /authorize
  ?response_type=code
  &client_id=3ae09536-db18-4de8-a68d-6539459702f0
  &redirect_uri=http%3A%2F%2F127.0.0.1%2Fcallback
  &scope=openid+profile

Authorization Response

Web server and browser-based clients must implement a "callback" function that is invoked by visiting a URI at the client. This callback will receive authorization codes, security tokens and error messages.

Exchanging Authorization Codes for Tokens

Clients exchanging authorization codes for security tokens at the /token endpoint must provide their registration access token in the Authorization header.

Token Request

POST /token HTTP/1.1
Host: your.authorization.server
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET)

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

Token Response

HTTP/1.1 200 OK
cache-control: no-store
pragma: no-cache
content-type: application/json

{
  "access_token":"6cb1a56021c4320fc93d",
  "token_type":"Bearer",
  "expires_in":3600,
  "refresh_token":"3f8a5a803a491748f77c",
  "id_token":"eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmFudmls
              LmlvIiwic3ViIjoiODY0YzM5M2ItMDUzZi00ZGY2LWI0NzctNDg3OWQzNjY2Y
              TZlIiwiYXVkIjoiM2FlMDk1MzYtZGIxOC00ZGU4LWE2OGQtNjUzOTQ1OTcwMm
              YwIiwiZXhwIjoxMzk4NjM0Mzk1OTAyLCJpYXQiOjEzOTg1NDc5OTU5MDJ9.R1
              pXMTBWdmZDNGFQelhaay1JckI4aGlzQ2tHT2NCVEVUNXRLY1FKTWQ2ZWFRZzR
              vaXZiR0hLTzNaMmVLNUZ1VjBaV0hYNi1remRsMFVibnZkdTRwdjJnMGpxbEJn
              UlNVa2ZpWWNOTDgzcGhrXzU3Y3licXpYTWx1dEIxRW5YZDYyMkZYOTAyOUNfb
              WJVT0FFV3BMczFZYWZFd3A0RXkybkRKWTRtdzd5a19LZFR6OF9iR25LUF9CaG
              x4ejg4MGVEUGpOMnZHaXVKdmNWak41T0J4OWU2TkJwWUFOc3NkS2lXQlpSc3I
              4SFZvbEpmd29xX290TngwenVERVlLRTVWa21CVndDY3lGNkRNRF9hVzNlRXJy
              bHBVQjFSY3k0UEdLX0hlNVU5Q1drRHIzbDY5bWlnNEJrd0c1MXpTYUtJcTFhR
              VhJSkZaODc3dm5zZHc2anVHYjdn"
}

Client Sessions