Permission requests and OAuth

A user can authorize a merchant to access various endpoints, typically shipping address or phone number. To enable this in the general case, we use OAuth 2.0. The Merchant API also has methods to support this.

OAuth terms and mCASH

The end user or customer is the resource owner, as the resource is typically user data or endpoints for doing something on the users behalf. The authorization server is mCASH, who is responsible for checking credentials and handing out tokens after the resource owner authorizes access. The Merchant is the client, who consumes the resource.

Application registration

The Merchant is implicitly a confidential OAuth client for the purposes of Merchant API calls, with their mCASH merchant_id as the client id. There is no need to register redirect URLs for Merchant API usage as the Merchant makes all the calls directly.

If the Merchant desires to use standard OAuth with redirects, it must register an application in Merchant API or in self service portal. This is equivalent to registering a client in OAuth language. This returns a client id and client secret. Those values can be used to set up standard OAuth client libraries, as they are separate from the regular merchant id and authentication.

OAuth authorization code grant

When we use regular OAuth, the authorization code grant flow is the default:

  • Client redirects user to authorization server endpoint, where user identifies and approves authorization. https://ssp.mca.sh/oauth/auth (or similar)
  • Authorization server redirects user back to client redirect_uri, with authorization code
  • Client exchanges authorization code for access token (https://ssp.mca.sh/oauth/token) using client credentials
  • Client accesses protected resource with access token

Merchant API permission request

In the Merchant API, there is an endpoint for requesting authorization POST /permission_request/, a direct callback with the access token, and an outcome endpoint GET /permission_request//outcome/ for checking the outcome later. As the resource owner does not have to carry tokens, there is no checking of redirect_uri and we don't need the authorization code.

Making payment requests

The access token can be used in the customer field when making payment requests at POST /payment_request/.

Scope values

If not requesting any scopes, the result is an access token that can be used as customer field for a payment request or a permission request. For more info on scopes, check out the specification for the protocol: http://openid.net/specs/openid-connect-basic-1_0-28.html#scopes

openid
To make a OpenID Connect request for login. NOTE: the openid scope is also required in order to access the address, phone, and email scopes, in line with the OAuth2 spec.
address
Included in GET /oauth2/v1/userinfo
phone
Included in GET /oauth2/v1/userinfo
email
Included in GET /oauth2/v1/userinfo
profile
Included in GET /oauth2/v1/userinfo. Currently this corresponds the claims ['name']. More may be added in the future. See the specification for the openid protocol for more info on this scope. http://openid.net/specs/openid-connect-basic-1_0-28.html#scopes

For Norwegian fodselsnummer, shipping_address, and specific personal id schemes like bankid, the endpoint URI is a little different.

shipping_address
GET /oauth2/v1/scope/shipping_address
verified fodselsnummer for user, listing proofs for jurisdiction
GET /oauth2/v1/scope/personal_id/no/id
verified fodselsnummer from BankID, single entry in proof list
GET /oauth2/v1/scope/personal_id/no/bankid

OpenID ID token

When using OpenID connect scopes, an id token is returned alongside the access token.

An ID Token is a cryptographically-signed JSON object encoded in base 64, represented as a JSON Web Token (JWT).

The fields used by mCASH are

iss : String : required
  • Data required (new or existing on update)
 Issuer Identifier for the Issuer of the response. The iss value is a case sensitive URL using the https scheme that contains scheme, host, and OPTIONALLY, port number and path components and no query or fragment components.
sub : String : required
  • Data required (new or existing on update)
  • length <= 255
 Subject identifier. A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client, e.g., 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4. The sub value is a case sensitive string.
aud : String : required
  • Data required (new or existing on update)
 Audience(s) that this ID Token is intended for. It MUST contain the OAuth 2.0 client_id of the Relying Party as an audience value. It MAY also contain identifiers for other audiences. In the general case, the aud value is an array of case sensitive strings. In the special case when there is one audience, the aud value MAY be a single case sensitive string.
exp : Integer : required
  • Data required (new or existing on update)
 Expiration time on or after which the ID Token MUST NOT be accepted for processing. The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See RFC 3339 for details regarding date/times in general and UTC in particular.
iat : Integer : required
  • Data required (new or existing on update)
 Time at which the JWT was issued. The time is represented as the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
at_hash : String : optional : default=null
  • Optional
 Provides validation that the access token is tied to the identity token. Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg parameter of the ID Token's JWS [JWS] header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them.
azp : String : optional : default=null
  • Optional
 The party to which the ID Token was issued. If present, it MUST contain the OAuth 2.0 client_id of the party that will be using it. This Claim is only REQUIRED when the party requesting the ID Token is not the same as the sole audience of the ID Token. It MAY be included even when the Authorized Party is the same as the sole audience.