BioID OAuth 2.0 Service

OAuth 2.0

BioID implements an authorization service based on the OAuth 2.0 authorization framework. The idea behind this implementation is to provide a simple biometric authentication service for face and/or voice recognition, which can be used by standard OAuth 2.0 client implementations to let their users log in using biometrics.

Please note that a client-ID and -secret is required to use the OAuth 2.0 service. In order to register and manage your clients, go to your profile page.

How to implement an OAuth 2.0 client

BioID Connect implements an OAuth 2.0 service according to RFC 6749. The authorization code grant flow might be especially interesting for you:

OAuth 2.0 code grant flow
  1. The user wants to login to your application.
  2. The application redirects the user to the authorization endpoint of the BioID Server. This initiates the authorization request.
  3. The user has to login and has to grant access in the consent-dialog:
    • the user might be authenticated already or has to log in explicitely using his/her credentials and/or biometrics
    • the consent-dialog only appears the first time a user logs in into your application
  4. The BioID Server redirects the user back to the return-URL within your application providing an authorization code.
  5. Using the authorization code the client application now requests an access- (and a refresh-) token from the token endpoint.
  6. Finally your client application uses the access token to call into a BioID API to request information about the logged in user.

The BioID OAuth 2.0 service is implemented as a .NET OWIN middleware component. Therefore we also provide an OWIN client middleware implementation which is available at GitHub and as a NuGet package.

Authorization Request

  • Authorization endpoint: https://account.bioid.com/oauth/authorization (only the HTTP method GET is supported)
  • Parameters: the following parameters need to be added to the query component of the request:
    response_type
    Required. Must be set to code.
    client_id
    Required. The client ID from your client registration.
    redirect_uri
    Required. Exactly one of the authorized redirect URIs is allowed.
    scope
    Optional (default is basic). Can be one or more (space separated) of the currently supported scope-tokens: basic, email, bcid
    state
    Recommended. An application specific, opaque value, which is returned in the callback to the redirect_uri.
  • Response: on success the server returns a redirect response (302) to the redirect URI with the following query parameters. Please note that there could also be an error response, or, in case of an invalid redirect URI, even a redirect to an error page.
    code
    The generated authorization code.
    state
    The same value as received in the state request parameter.

Token Request

  • Token endpoint: https://account.bioid.com/oauth/token
  • Authentication: only HTTP basic access authentication is supported (using the client-ID and -secret from your client registration)
  • Parameters: the following parameters need to be added to the request entity-body:
    grant_type
    Required. Must be set to authorization_code.
    code
    Required. The authorization code received from the authorization request.
    redirect_uri
    Required. Exactly one of the authorized redirect URIs is allowed.
    client_id
    Required. The client ID from your client registration.
  • Response: on success the server issues an access token and a refresh token and returns them in a success (200) response with the following parameters in the entity-body. Please note that there could also be an error response (400).
    access_token
    The issued access token.
    token_type
    We currently issue bearer tokens.
    expires_in
    The lifetime of the access token in seconds.
    refresh_token
    The issued refresh token.

User-Information API

  • API endpoint: https://apis.bioid.com/people/me
  • Authentication: Use the issued bearer token, e.g.
      GET /people/me HTTP/1.1
      Host: apis.bioid.com
      Authorization: Bearer xxxxx
    
  • Response: on success the API returns:
    id
    A unique user ID for the logged in user.
    name
    The name of the user (might be an alias).
    profile
    The link to a web page where the user can manage his or her BioID profile.
    email
    Only if requested: the email address of the user, if available and confirmed.
    bcid
    Only if requested: the Biometric Class ID of the user. Can be used by client applications that are calling directly into the BioID Web Service.