Authentication Madagascar (orange.mg) API
authorization : obtain user's consent
implementation notes
In order to obtain OpenID Connect/OAuth tokens (i.e. id_token, access_token, refresh_token), you first need to request an "authorization code" as defined in OAuth 2.0 and OpenID Connect. At this stage, the Orange Authorization Server may need to authenticate the end-user and receive his permission before releasing the "Authorization Code". This call will redirect the end-user to a login form and then to your callback URL as you have defined it in Orange Partner.
parameters
parameter value description parameter type data type code (default)(required)Must be set to 'code' for authorization request. query string (required)Your client identifier (from Orange Partner developer website). query string (required)The URL on your server where the end-user will be redirected after authentication. It must match the URL you provided when you registered for Orange Partner. Remember to URL-encode special characters such as :, /, %, ?, &... query string openid (default)(required)The scope your application needs. It tells our Orange Authorization server what kind of permissions to asks for when displaying the consent form to the end-user. The scope value 'openid' is mandatory. query string (required)Free parameter to set some data. This field will be sent back in the query-string when redirecting to your callback URL. query string Used to associate a client session with the ID Token. It is passed unmodified from Authorisation Request to ID Token. The value should be unique per session to mitigate replay attacks. query string Authentication Context class Reference. Space separated string (e.g. 2,3) that specifies the Authentication Context Reference to be used during authentication processing. The LOA required by the RP/Client for the use case can be used here. The values appear as order of preference. The acr satisfied during authentication is returned as acr claim value query string An indication to our Orange IDP/Authorisation Server on what ID to use for login, e.g. email, MSISDN (phone_number), etc. It is recommended that the value matches the value used for discovery. query string Specify the user interface display for the Authentication and Consent flow. Supported values are: page (default), popup, touch and wap. query string Space delimited (Caution: url-encoded space (%20) is required), case-sensitive ASCII string values to specify to the Authorisation Server whether to prompt or not for reauthentication and consent. Supported value values are: - none: no UI will be displayed (Caution : if end-user is not logged in, or has not consented yet, an error will occur) - login: forces the authentication display even if already logged in - consent: forces the consent page display even if end-user consent was already collected - select_account: not supported. query string Specify the maximum elapsed time in seconds since last authentication of the user. If the elapsed time is greater than this value, a reauthentication must be done. query string Space separated list of user preferred languages and scripts for the UI as per RFC5646. query string Non supported by our Orange Authorization server. Generally used in conjunction with prompt=none to pass the previously issued ID Token as a hint for the current or past authentication session. If the ID Token is still valid and the user is logged in then the server returns a positive response, otherwise should return a login_error response. query string Non supported by our Orange Authorization server. Separated list of user preferred languages and scripts for the Claims being returned as per RFC5646. query string Not supported by our Orange Authorization server. Data to be signed by the private key owned by the end-user (mandatory for LOA=4 use cases). query string response messages
List of common error codesHTTP status code reason response model 302 (success) If succeed, the Orange Authorization Server informs the client by adding the following parameters to the query component of the redirection URI (see Location header):
- code (required): authorization code (with a lifetime of about 10 minutes),
- state (required): identical as the state value added in the request,
- scope (optional)): validated scope (if different than those requested by the application)."Location: <redirect_uri>?code=<auth_code>&state=<state>[&scope=<scope>]"
302 (errors) In case of error, the Orange Authorization Server informs the client by adding the following parameters to the query component of the redirection URI (see Location header):
- error (required): single ASCII error code
- error_description (optional): Human-readable ASCII text providing additional information, used to assist the developer in understanding the error that occurred.
- state (required): identical as the state value added in the request,
List of possible error codes:
- invalid_request: a required parameter is missing in the request, or a parameter value is unknown.
- unsupported_response_type: the authorization server does not support obtaining an authorization code using this method.
- unauthorized_client: the authenticated client is not authorized to use this authorization grant type.
- access_denied: the end-user cancelled the consent form.
- invalid_scope: the given scope does not match known one.
- login_required: the user is not authenticated, you have to send the request again without prompt=none so the UI sequence is processed.
- consent_required: the user has never accepted the TOS, you have to send the request again without prompt=none so the UI sequence is processed.
- server_error: an internal server error occurred and the request can not be fulfilled.
- temporarily_unavailable: the request could not be currently handled."Location: <redirect_uri>?error=<code>&error_description=<description>&state=<state>"
implementation notes
In order to obtain OpenID Connect/OAuth tokens (i.e. id_token, access_token, refresh_token), you first need to request an "authorization code" as defined in OAuth 2.0 and OpenID Connect. At this stage, the Orange Authorization Server may need to authenticate the end-user and receive his permission before releasing the "Authorization Code". This call will redirect the end-user to a login form and then to your callback URL as you have defined it in Orange Partner.
parameters
parameter value description parameter type data type code (default)(required)Must be set to 'code' for authorization request. formData string (required)Your client identifier (from Orange Partner developer website). formData string (required)The URL on your server where the end-user will be redirected after authentication. It must match the URL you provided when you registered for Orange Partner. Remember to URL-encode special characters such as :, /, %, ?, &... formData string openid (default)(required)The scope your application needs. It tells our Orange Authorization server what kind of permissions to asks for when displaying the consent form to the end-user. The scope value 'openid' is mandatory. formData string (required)Free parameter to set some data. This field will be sent back in the query-string when redirecting to your callback URL. formData string Used to associate a client session with the ID Token. It is passed unmodified from Authorisation Request to ID Token. The value should be unique per session to mitigate replay attacks. formData string Authentication Context class Reference. Space separated string (e.g. 2,3) that specifies the Authentication Context Reference to be used during authentication processing. The LOA required by the RP/Client for the use case can be used here. The values appear as order of preference. The acr satisfied during authentication is returned as acr claim value formData string An indication to our Orange IDP/Authorisation Server on what ID to use for login, e.g. email, MSISDN (phone_number), etc. It is recommended that the value matches the value used for discovery. formData string Specify the user interface display for the Authentication and Consent flow. Supported values are: page (default), popup, touch and wap. formData string Space delimited (Caution: url-encoded space (%20) is required), case-sensitive ASCII string values to specify to the Authorisation Server whether to prompt or not for reauthentication and consent. Supported value values are: - none: no UI will be displayed (Caution : if end-user is not logged in, or has not consented yet, an error will occur) - login: forces the authentication display even if already logged in - consent: forces the consent page display even if end-user consent was already collected - select_account: not supported. formData string Specify the maximum elapsed time in seconds since last authentication of the user. If the elapsed time is greater than this value, a reauthentication must be done. formData string Space separated list of user preferred languages and scripts for the UI as per RFC5646. formData string Non supported by our Orange Authorization server. Generally used in conjunction with prompt=none to pass the previously issued ID Token as a hint for the current or past authentication session. If the ID Token is still valid and the user is logged in then the server returns a positive response, otherwise should return a login_error response. formData string Non supported by our Orange Authorization server. Separated list of user preferred languages and scripts for the Claims being returned as per RFC5646. formData string Non supported by our Orange Authorization server. Data to be signed by the private key owned by the end-user (mandatory for LOA=4 use cases). formData string response messages
List of common error codesHTTP status code reason response model 302 (success) If succeed, the Orange Authorization Server informs the client by adding the following parameters to the query component of the redirection URI (see Location header):
- code (required): authorization code (with a lifetime of about 10 minutes),
- state (required): identical as the state value added in the request,
- scope (optional)): validated scope (if different than those requested by the application)."Location: <redirect_uri>?code=<auth_code>&state=<state>[&scope=<scope>]"
302 (errors) In case of error, the Orange Authorization Server informs the client by adding the following parameters to the query component of the redirection URI (see Location header):
- error (required): single ASCII error code
- error_description (optional): Human-readable ASCII text providing additional information, used to assist the developer in understanding the error that occurred.
- state (required): identical as the state value added in the request,
List of possible error codes:
- invalid_request: a required parameter is missing in the request, or a parameter value is unknown.
- unsupported_response_type: the authorization server does not support obtaining an authorization code using this method.
- unauthorized_client: the authenticated client is not authorized to use this authorization grant type.
- access_denied: the end-user cancelled the consent form.
- invalid_scope: the given scope does not match known one.
- login_required: the user is not authenticated, you have to send the request again without prompt=none so the UI sequence is processed.
- consent_required: the user has never accepted the TOS, you have to send the request again without prompt=none so the UI sequence is processed.
- server_error: an internal server error occurred and the request can not be fulfilled.
- temporarily_unavailable: the request could not be currently handled."Location: <redirect_uri>?error=<code>&error_description=<description>&state=<state>"
common : common resources
implementation notes
Returns the status
response class (status 200)
{ "name": "myproxy_v1", "status": "ok", "version": "1.0.9", "components": [ { "status": "ok", "version": "v1.1", "name": "redis" } ] }
response messages
List of common error codesHTTP status code reason response model 503 http status { "name": "myproxy_v1", "status": "ok", "version": "1.0.9", "components": [ { "status": "ok", "version": "v1.1", "name": "redis" } ] }
default Error [ { "code": 23, "message": "Missing body field", "description": "The field 'productionDate' is missing from posted body" } ]
refresh token : renew access token
implementation notes
You can also use a previously obtained "refresh token" to request a new "access token" (without necessarily having the end-user "online").
response class (status 200)
{ "token_type": "Bearer", "access_token": "string", "expires_in": 0 }
parameters
parameter value description parameter type data type (required)The Authorization with valid app's credentials header string refresh_token (default)(required)The value must be "refresh_token". formData string (required)The refresh token received from the authorization server formData string Requested scope (it must not include any scope not originally granted, and if omitted is treated as equal to the scope originally granted when the refresh token was issued). formData string response messages
List of common error codesHTTP status code reason response model 400 Bad Request. List of error codes:
- invalid_request: a required parameter is missing in the request, or a parameter value is unknown.
- invalid_grant: the provided authorization grant (e.g., authorization code) or refresh token is invalid, expired, revoked, etc.
- unauthorized_client: the authenticated client is not authorized to use this authorization grant type.
- unsupported_grant_type: the authorization grant type is not supported by our authorization server.
- invalid_scope: the requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.{ "error": "string", "error_description": "string" }
401 Unauthorized. List of error codes:
- invalid_client: client authentication failed (e.g., unknown client_id).{ "error": "string", "error_description": "string" }
default Common error list [ { "code": 23, "message": "Missing body field", "description": "The field 'productionDate' is missing from posted body" } ]
tokens : get access token, [id_token], [refresh_token]
implementation notes
You can now exchange the obtained "authorization code" for tokens. You must make this call in order to obtain a token that you will use either directly with each subsequent calls to other API.
response class (status 200)
{ "token_type": "Bearer", "access_token": "string", "expires_in": 0, "scope": "string", "refresh_token": "string", "id_token": "string" }
parameters
parameter value description parameter type data type (required)The Authorization with valid app's credentials header string authorization_code (default)(required)Fixed value. To be set with 'authorization_code' value. formData string (required)It must contain the code you received in the callback query-string when you called the /authorize. formData string (required)It must be set to the callback URL you provided at registration. Note that it is mandatory for security reasons. formData string response messages
List of common error codesHTTP status code reason response model 400 Bad Request. List of error codes:
- invalid_request: a required parameter is missing in the request, or a parameter value is unknown.
- invalid_grant: the provided authorization grant (e.g., authorization code) or refresh token is invalid, expired, revoked, etc.
- unauthorized_client: the authenticated client is not authorized to use this authorization grant type.
- unsupported_grant_type: the authorization grant type is not supported by our authorization server.
- invalid_scope: the requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.{ "error": "string", "error_description": "string" }
401 Unauthorized. List of error codes:
- invalid_client: client authentication failed (e.g., unknown client_id).{ "error": "string", "error_description": "string" }
default Common error list [ { "code": 23, "message": "Missing body field", "description": "The field 'productionDate' is missing from posted body" } ]