Authenticating on the Web

How did we do?

Traditionally with HiveMP Sessions you authenticate by directly sending requests to the PUT /authenticate endpoint. However, when authenticating HTML5 and other browser-based applications, you need to authenticate through our OAuth process.

Requirements for Authenticating on the Web

There are several requirements to authenticate a web-based application again HiveMP Sessions:

  • You must be able to create a TXT record against the domain your application will be served from.
  • The project you are authenticating into must be marked as Discoverable and have all the required fields filled out, including Website URL.
  • The project's Website URL must be the URL and domain your application will be served from.
  • You must create a public API key for the project, which will be used as the client_id.
  • Your website must be served on HTTPS. You can not authenticate users in HiveMP Sessions if you are serving over HTTP.

You can set up a project to meet these requirements in the Admin Console.

Initiating an Authentication Request

If your application does not have a valid session, you should direct the user to the following URL:

https://account.hivemp.com/oauth?client_id=YOUR_CLIENT_ID_HERE&redirect_uri=YOUR_REDIRECT_URI

The available query parameters are:

  • client_id - Mandatory. This must be a public API key for the project you are authenticating into.
  • redirect_uri - Mandatory. This must be the URI to redirect the user to after authentication is successfully. It must exactly match or be a descendant of the project's Website URL. It must also be a HTTPS URL.
  • requested_role - Optional. If this is specified, the session will be created with the requested role if possible.
  • show_legacy_login_link - Optional. If true, the page displays a link to the Admin Console (Legacy Login).

Receiving an Authentication Request

When the session have been created, the user will be redirected to:

YOUR_REDIRECT_URI#session=SESSION_DATA

For example, if your redirect_uri is set to https://example.com/some/path/, then the user will be redirected to:

https://example.com/some/path/#session=SESSION_DATA

SESSION_DATA is a base64-encoded, JSON representation of UserSessionWithSecrets.

You should verify that the received session and API key is for the correct project by performing the following tasks in sequence:

  • Make a request to GET /project/public without a project ID. This will return the public project information for the API key that the session actually belongs to. Verify that the returned project ID matches the one your application expects.
  • Next, make a request to GET /session without a session ID. This will return the session information for the API key. Verify that the session ID matches the one provided in the session data.