Authorization Code Flow: Obtain Access Token

authorize and authenticate client applications using the oauth authorization code flow get access tokens for connect api access raidiam recommends reading the obtaining access tokens docid 5miarxigf9evyopcotzkf article first to learn about used specifications, all available access scopes and what they enable, and more for a sample postman collection, see the authorization code flow obtain access token docid 0z3ot2yen n x48j6cwla section sequencediagram autonumber participant user as super user participant app as client application participant as as raidiam authorisation server participant api as connect apis app >>app prepare and sign request object if needed app >>as /par note over app,as the request also contains\<br /> all pkce related parameters note over app,as scope=directory\ website as >>app request uri=xyz app >>as auth?request uri=xyz as >>user redirect user to login screen user >>as authenticate user >>as consent as >>user redirect back to application as >>app code app >>as /token + code note over app, as the request uses tls client auth\<br /> or private key jwt\<br /> client auth method note over app,as scope=directory\ website as >>app access token app >>api call api with token prerequisites users docid\ ijyftusvdonrn4rxsnsev access to the platform or user type with appropriate permissions a ctive and valid applications docid\ at1zjk4wwrastj pdhvhx (software statement) with the scope directory\ website granted if not yet added, add and manage applications docid x1gpnkw44xyryobh6wp6 make sure your organisation has a assign roles to organisations docid\ e3nwfhzwmlwbeoohvjfp7 that enables the organisation resources to request the directory\ website scope and add application roles docid\ yotcq4bxhcuwao2b w iz active transport certificates docid\ g ci bmrum8en1ffwnzi if not yet added, manage certificates for organisation docid\ rfyhtnlocobktfbja2o1o for organisation (shared between apps) or application (associated with a single app only) active signing certificates docid\ g ci bmrum8en1ffwnzi along with a public and private keys docid\ xb31qsym6rjvvzucnk1ex if your application is required to use signed request objects or uses the private key jwt client authentication method if not yet added, manage certificates for organisation docid\ rfyhtnlocobktfbja2o1o for organisation get token using auth code flow add raidiam's authorisation server / well known endpoint to your oauth library configuration your oauth library should be able to get the server's configuration sample / well known https //auth sandbox raidiam io/ well known/openid configuration https //auth sandbox raidiam io/ well known/openid configuration the / well known endpoint contains all the information about the servers docid\ epvkxzuzz6ldhyv nyms you need to successfully integrate with the server and get access tokens, for example pushed authorisation request (par) endpoint "pushed authorization request endpoint" "https //auth sandbox raidiam io/request" oauth authorization endpoint " authorization endpoint" "https //auth sandbox raidiam io/auth" oauth token endpoint for clients authenticating themselves using the private key jwt method "token endpoint" "https //auth sandbox raidiam io/token" mtls endpoint aliases for clients authenticating themselves using the tls client auth method sample mtls endpoint aliases "mtls endpoint aliases" { "token endpoint" "https //matls auth sandbox raidiam io/token", "revocation endpoint" "https //matls auth sandbox raidiam io/token/revocation", "introspection endpoint" "https //matls auth sandbox raidiam io/token/introspection", "device authorization endpoint" "https //matls auth sandbox raidiam io/device/auth", "registration endpoint" "https //matls auth sandbox raidiam io/reg", "userinfo endpoint" "https //matls auth sandbox raidiam io/me", "pushed authorization request endpoint" "https //matls auth sandbox raidiam io/request", "backchannel authentication endpoint" "https //matls auth sandbox raidiam io/backchannel" } manage certificates for organisation docid\ rfyhtnlocobktfbja2o1o for your organisation and add it to your oauth library client's configuration the transport certificate will be used in mutual transport layer security (mtls) to establish a secure connection between your client and the authorisation server your oauth client library should be capable of verifying the authorisation server's certificate if you are using curls to test the integration, you can disable checking the server's certificate using the k flag or insecure option if needed, prepare a signed request object ( rfc9101 ) with the authorization request parameters this step is not required if the require signed request object option is disabled in advanced application configuration you can check it in applications > your application > advanced configuration view if you are a super user and the role attached to the application is of the directory type the parameters are represented as the json web token (jwt) claims of the object additionally, the jwt should contain the iss (issuer your client id) and aud (audience the authorisation server url) claims signed request object payload example { "client id" "19283akf98", "aud" "https //auth sandbox raidiam io", "iss" "19283akf98", "exp" 1723734583, "nbf" 1723734283, "response type" "code", "code challenge method" "s256", "nonce" "gxgldlyaatu", "scope" "openid trust framework profile directory\ website", "claims" { "id token" { "trust framework profile" { "essential" true } } }, "redirect uri" "https //www example com", "state" "xyaaaabc124", "code challenge" "rv7lirb2it4nyxnlvqrkoazwf9gb1o3ekinda8wqlha", "response mode" "query jwt" } to sign the jwt, utilize json web signature ( jws rfc7515 ) and a signing key added within your organisation push the contents of the authorization request to the raidiam's pushed authorization request (par) /requests endpoint pushed authorization requests, defined by the rfc9126 specification, enable client applications to push the payload of the authorization request directly to the oauth authorisation server and receive a request uri in exchange as a reference to the authorization request payload data in the subsequent call to the authorization endpoint below you can find example requests to the raidiam's /request (par) endpoint if signed request objects are not required curl to /request (par) template curl location request post 'https //{base url}/request'\\ \ cert /path/to/your/certificate pem \\ \ key /path/to/your/private key \\ \ header 'content type application/x www form urlencoded' \\ \ data urlencode 'response type={response type}' \\ \ data urlencode 'client id={client id}' \\ \ data urlencode 'scope=\[scopes]' \\ \ data urlencode 'redirect uri=\[redirect uris]' \\ \ data urlencode 'state={state}' \\ \ data urlencode 'code challenge method=s256' \\ \ data urlencode 'code challenge={code challenge}' \\ \ data urlencode 'response mode=query jwt' sample call with values curl location request post 'https //matls auth sandbox directory openbankingbrasil org br/request'\\ \ cert /path/to/your/certificate pem \\ \ key /path/to/your/private key \\ \ header 'content type application/x www form urlencoded' \\ \ data urlencode 'response type=code' \\ \ data urlencode 'client id=4674878c 0653 4348 875a 4e99eef993c5' \\ \ data urlencode 'scope=directory\ website' \\ \ data urlencode 'redirect uri=https //www example com' \\ \ data urlencode 'state=xyaaaabc124' \\ \ data urlencode 'code challenge method=s256' \\ \ data urlencode 'code challenge=hipqwzjoa3ipm4ztwkbqwnn qf3yx9tv5s 0idpqvlw' \\ \ data urlencode 'response mode=query jwt' in oauth, scope is a mechanism to limit an application's access to a user's account an application can request one or more scopes this information must be included in the call to the par endpoint, oauth authorization endpoint, and oauth token endpoint is presented to the user in the consent screen (after the call to the oauth authorization endpoint) the access token issued to the application is limited to the scopes granted by the user in raidiam connect, the scopes your application can request are determined by the application's role and its associated metadata to request the directory\ website scope, the application needs to have the scope role metadata type assigned with the value set to directory\ website note that the application role is not the value of the scope parameter for read/write operations, the scope parameter value needs to be directory\ website as a response to your request, you receive a request uri you can use in the subsequent call to the authorization endpoint redirect the user to the raidiam's oauth authorization /auth endpoint including the received request uri and client identifier in the query parameters sample url https //{base url}/auth?request uri={request uri}\&client id={client id} the user authenticates and provides their consent once the user provides their consent, they get redirected back to your application to the redirect url configured for your application extract the authorization code from the redirect url call the raidiam's oauth /token endpoint to authenticate your client utilize the client authentication method configured for your client tls client auth mutual tls client authentication and certificate bound access tokens rfc8705 private key jwt assertion framework for oauth 2 0 client authentication rfc7521 curl to /token template curl location request post 'https //{base url}/token' \\ \ cert /path/to/your/certificate pem \\ \ key /path/to/your/private key \\ \ header 'content type application/x www form urlencoded' \\ \ data urlencode 'grant type=authorization code' \\ \ data urlencode 'client id={client id}' \\ \ data urlencode 'code={code}' \\ \ data urlencode 'redirect uri={redirect uri}' \\ \ data urlencode 'code verifier={code verifier}'curl location request post 'https //matls auth sandbox directory openbankingbrasil org br/token' \\ \ cert /path/to/your/certificate pem \\ \ key /path/to/your/private key \\ \ header 'content type application/x www form urlencoded' \\ \ data urlencode 'grant type=authorization code' \\ \ data urlencode 'client id=4674878c 0653 4348 875a 4e99eef993c5' \\ \ data urlencode 'code=krmunyh9rdmf2dxyolyrtwcjd3usk6uhmkmioi 98k6' \\ \ data urlencode 'redirect uri=https //www example com' \\ \ data urlencode 'code verifier=j03x d6v86crliftpuguusqoxatfdt2nfwahijpwzeq' upon successful validation of the request, the authorisation server issues and returns an access token in a form of a jwt signed using the algorithm configured for your client ( applications > your application > advanced configuration > token signed response algorithm id ) call the connect api using the access token you got from the authorisation server by default, applications are configured to receive certificate bound access tokens where information about the certificate used to get the token is included in the token itself and verified by the raidiam's resource server (apis) make sure to utilize the same certificate across all mtls connections with the authorisation server and raidiam's apis sample postman collections for authorization code flow you can utilize the below postman collections to quickly test client authentication for read/write access tokens with par, pkce, mtls client authentication, and when signed request objects are required https //archbee doc uploads s3 amazonaws com/ld4qjosp 4frema90f36r 8wknhhw0cixoxuos4drui 20240828 095030 json when signed request objects are not required https //archbee doc uploads s3 amazonaws com/ld4qjosp 4frema90f36r mezn8o j6jud2 xa hanb 20240828 095150 json import the json with collection configuration into postman and add your organisation or an application transport certificate to postman configuration for more information on how to add a certificate in postman, see the add and manage ca and client certificates in postman article