FAST LOGIN API

Authentication Endpoint

Authentication Endpoint URL: https://hizligiris.com.tr/hizligiris/oauth/authorize

http method: GET

Sample URL https://hizligiris.com.tr/hizligiris/oauth/authorize?client_id=client&scope=openid%20phone&redirect_uri=https://mylocalhost.com&response_type=code&state=State0.p26wdplbsx5k1972v5cdi&nonce=Nonce0.vdl4rjul2btzy24wnimabrzfr&prompt=login&acr_values=2&display=page&ui_locales=tr&claims_locales=tr

Mandatory Parameters

URI Parameter Description
*client_id This is your application id from your settings on Fast Login Platform
Type: String
*scope A space-delimited list of the permissions you are requesting
Type: String
  • openid *Mandatory
  • phone
  • profile
  • email
*redirect_uri Where Fast Login sends the user after the user grants or denies consent. If user approves then Service Provider should get authentication_code with this URI. If there is more than one redirect uri, Service Provider should get authentication_code for each redirect uri.
Type: URI
*response_type The value MUST be "code", to indicate that the grant type flow to be used is Authorisation Code.
Type: String
*acr_values The recommended values are the LOAs as specified in ISO/IEC 29115 Clause 6 - 1, 2, 3, 4 - representing the LOAs of LOW, MEDIUM, HIGH and VERY HIGH
Type: String
*state This parameter will also be added to the redirect URI and it is for against cross-site request forgery (CSRF)
It should be produced as random for each request
Type: String
*nonce The value SHOULD be unique per session to mitigate replay attacks
Type: String

About Scope Parameter:

Fast Login "scope" values determine the specific set of claim values to return in the response.
Scope values definition:
The scope value "openid" is mandatory to indicate that the request is an OpenID Connect request. The other scope values are related to the UserInfo.

Value Mandatory in Spec Mandatory in Profile Description
*openid *Mandatory *Mandatory This value indicates the Request is an OpenID Connect request.
*profile Optional Optional Requests access to the default basic profile claims: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.
*email Optional Optional Request access to the claims : email and email_verified
*address Optional Optional Requests access to the claim : address
Currently not provided by Fast Login
*phone Optional Optional Requests access to the claims : phone_number and phone_number_verified

About ACR Values:

How are the levels defined in Fast Login?
Within Fast Login there are 2 levels of assurance identified as per the ISO/IEC 29115 Clause 6:

Level Description Exists in Fast Login? ACR Value
2 - Medium Some confidence in the asserted identity
(Something you have).		 Yes 2
3 - High High confidence in the asserted identity
(Something you have and something you know).		 Yes 3

Optional Parameters:

URI Parameter Description
*display specifies the user interface display for the Authentication and Consent flow. Now, only "page" is supported
Type: String
*prompt specify to the Authorisation Server whether to prompt or not for reauthentication and consent.
Now, only "login" is supported
Type: String
*login_hint An indication to the IDP/Authorisation Server on what ID to use for login.
The login_hint can contain the MSISDN or the Encrypted MSISDN and SHOULD be tagged as MSISDN:<Value> and ENCR_MSISDN:<Value> respectively - in case MSISDN or Encrypted MSISDN is passed in login_hint. Encrypted MSISDN value is returned by Discovery API in the form of "subscriber_id"
MSISDN must be encrypted with Fast Login public key that is provided by Turkcell
This parameter is only used for if Service Provider implements its own Login page
Type: String
*ui_locales
claims_locales 		Specifies the language used in Fast Login pages, supported values:
  • en (English), tr (Turkish)
  • Default value is Turkish
  • Otherwise, "unsupported language" error will be returned
Type: String

Redirect URI

  • The client MUST provide one or more "redirect uri" to be used for responding back for Authorisation Requests through redirect.
  • Redirect URI is a simple http listener that takes authentication code from Fast Login Platform.
  • Service Providers have to provide their "redirect uri" while registration.
  • You can see furthermore details on the next "Response" section.
  • Redirect URI could be any it is up to Service Provider's responsibility to set the correct redirect URI

Response

  • Fast Login Authentication Response is met by the Redirect URI of the Service Provider.
  • So, in redirect uri Service Provider has to check the code first from the query parameter
    • If code exists then go for token by exchange code
    • If not then Service Provider should watch the error parameter
  • State parameter is used to avoid the reply attacks
Success Response URL Sample
https://mylocalhost.com/?code=5a032d59-47f6-4c83-8135-cd38784137db&state=State0.p26wdplbsx5k1972v5cdi
Fail Response URL Sample
https://mylocalhost.com/?state=State0.p26wdplbsx5k1972v5cdi&error=USER_DID_NOT_APPROVE
URI Parameter Description
*code Authorisation Code as per OAuth 2.0. To be used as parameter in Token request to exchange for Tokens
Type: String
*state The same value as the "state" parameter sent during the authentication request. Use as a security mechanism to confirm that the response comes from the same authentication requests
Type: String
*error if code parameter is missing in the response then Service Provider should check the error parameter.
USER_DID_NOT_APPROVE: User denies from Click Ok, it comes only for ClickOK authentication type
FRAUD_DETECTED: when user tries to break the authentication urls
BROKEN_SESSION: when user session is expired or does not exist
TIMED_OUT: when authentication messages are expired
Type: String
When Authentication URL is called from mobile applications;
  • IOS:
    • SFSafariViewController class or WKWebView class can be used instead of switching to Safari
    • UIWebView class is not supported
  • Android:
    • WebView should be used instead of switching to the default browser
    • Using Chrome Custom Tabs is not supported
When Authentication URL is called from mobile web browser;
    You should directly call the auth url ( exp: fulltrip.com , arikovani.com )
 When Authentication URL is called from desktop web browser;
    You should call the auth url in the popup window