Documentation Documentation

Authentication Type Flags

By default, Tyk will revert to a simple authentication token scheme unless these flags and their metadata are set (setting all of these to false will enable standard token mode).

This scheme basically means that you could send an authentication parameter and its value (the API key) along with the request and Tyk will attach it to a session, just like a bearer token in OAuth or a session key in cookie-based setups.

However Tyk supports many more methods, and these can be set by enabling these flags (and their associated metadata).

  • use_keyless: This will switch off all key checking and open the API definition up, some analytics will still be recorded, but rate-limiting, quotas and security policies will not be possible (there is no session to attach requests to). This is a good setting for checking if Tyk works and is proxying traffic correctly.
    This method has no additional metadata settings.

  • use_basic_auth: This method will enable basic auth as specified by the HTTP spec, an API with this flag set will request for a username and password and require a standard base64 Authentication header to be let through.
    Keys cannot be generated by Tyk for this method and need to use the /tyk/keys/add method with the basic_auth_data metadata set in the keys session configuration (see Basic Authentication and the overview of the Session Object in this use case under Key Management).

  • enable_signature_checking: a.k.a HMAC signing. If this option is set to true, Tyk will attempt to implement the HMAC signing standard as proposed in the HTTP Signatures Spec. In particular the structure of the Authorisation header and the encoding method need to be taken into account.
    This method will use a session key to identify a user and a user secret that should be used by the client to sign each request's date header.
    This method will also introduce clock skew checks, requests outside of 300ms of the system time will be rejected.
    This method is not recommended for Single-Page-Webapps (SPA) or Mobile apps due to the fact that secrets need to be distributed.

  • hmac_allowed_clock_skew: Set this value to anything larger than 0 to set the amount of milliseconds that will be tolerated for clock skew. Set to 0 to prevent clock skew checks on requests (only in HMAC mode).

  • use_oauth2: Tyk attempts to implement a semi-seamless OAuth2 flow. Given the nature of OAuth2's three-party system, it is difficult to implement as a proxy without significantly compromising security or usability.
    Enabling this option will cause Tyk to add OAuth2-standard endpoints to the API for /authorize and /token, these will supersede any other requests to your proxied system in order to enable the flow.
    Please see the OAuth2 Flow section for a comprehensive discussion of how to integrate with Tyk.

  • oauth_meta.allowed_access_types: Should be a string array of OAuth access options, types can be:

  • authorization_code - client has an authorisation code to request a new access token.

  • refresh_token - client can use a refresh token to refresh expired bearer access token.

Note: If using auth codes and refresh tokens, Tyk needs to notify your webapp of newly issued keys - it does this via web hook. See the section on notifications.

  • oauth_meta.allowed_authorize_types: Should be a string array of OAuth authorisation types - options that are supported are:

    • code - Client can request an authorisation code which can be used to request an access code via a server request (traditionally reserved for server-side apps).
    • token - Client can request an access token directly, this will not enable refresh tokens and all tokens have a 12 hour validity. Recommended for mobile apps and single-page webapps.
  • oauth_meta.auth_login_redirect: The Tyk OAuth flow has a dummy (intercept) /authorize endpoint which basically redirects the user to your login and authentication page, it will also send along all OAuth data as part of the request (so as to mimic a regular app flow).
    This is the URL that the user will be sent to (via POST).

Note: This interface method is only supported by modern browsers that respect a 307 redirect (retaining method and data), and varies between browsers.

  • notifications: When Tyk implements an OAuth2 flow, because it will handle access requests on your behalf once authorisation codes have been issued, it will need to notify your system that these have occurred.
    It will POST key data to the URL set in these options to ensure that your system is synchronised with Tyk.

  • notifications.shared_secret: Posted data to your service will use this shared secret as an authorisation header. This is to ensure that messages being received are from Tyk and not from another system.

  • notifications.oauth_on_keychange_url: The URL that will be sent the updated information - the URL will be polled up to 3 times if there is a communications failure. On a 200 OK response it stops.

  • auth: The auth section handles the standard Tyk authentication method, and if none of the above are set, will be the method used to authenticate requests.

  • auth.auth_header_name: The header carrying the authentication token.

  • auth.use_param: This will force Tyk to look for the auth_header_name value in the URL querystring parameters instead of in the header.

  • auth.param_name: Added in v2.1, set this to the parameter name to use to extract the auth token if it is empty, then the header name will be used instead.

  • auth.use_cookie: This will force Tyk to look for the auth_header_name value in a cookie.

  • auth.cookie_name: Added in v2.1, this will set the cookie name to use, if blank, then the auth_header_name value will be used.

  • strip_auth_data: When set to true, auth related headers will be stripped from requests proxied through the gateway.