More and more websites, communities and online projects are choosing to delegate authentication to external identity providers rather than managing user accounts and passwords directly.

For this reason, SimosNap IRC Network provides an OAuth 2.0 and OpenID Connect authentication system that allows developers to integrate SimosNap login into their own applications.

In this guide we'll see how the integration works and how to get started quickly.

Why use OAuth?

Managing a login system requires time, maintenance and constant attention to security.

By using OAuth:

  • You don't need to manage user passwords.
  • You don't need to implement password recovery procedures.
  • You don't need to worry about credential security.
  • You can leverage the existing SimosNap identity system.

Users authenticate directly on SimosNap servers and your application only receives the information they have authorized.

Registering an Application

To use the OAuth system, you must first register an application in your SimosNap account.

During registration, the following credentials are generated:

  • Client ID
  • Client Secret
  • Authorized Redirect URIs
  • Allowed Scopes

Example

CLIENT_ID=my_application_123456789
CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx
REDIRECT_URI=https://example.org/oauth/callback.php

Available Endpoints

Authorization Endpoint

https://www.simosnap.org/rest/service.php/oauth/authorize

Token Endpoint

https://www.simosnap.org/rest/service.php/oauth/token

UserInfo Endpoint

https://www.simosnap.org/rest/service.php/oauth/userinfo

Step 1: Redirect the User

When a user clicks the "Sign in with SimosNap" button, they must be redirected to the OAuth authorization endpoint.

Authorization Request

$clientId = 'my_application_123456789';
$redirectUri = 'https://example.org/oauth/callback.php';

$state = bin2hex(random_bytes(16));

$_SESSION['oauth_state'] = $state;

$params = [
    'response_type' => 'code',
    'client_id'     => $clientId,
    'redirect_uri'  => $redirectUri,
    'scope'         => 'openid profile irc',
    'state'         => $state
];

header(
    'Location: https://www.simosnap.org/rest/service.php/oauth/authorize?' .
    http_build_query($params)
);

exit;

The state parameter is generated randomly and stored in the user's session to protect the application against CSRF attacks.

Step 2: Receive the Authorization Code

After the user authenticates and grants consent, SimosNap redirects the browser back to your callback URL.

Redirect Example

https://example.org/oauth/callback.php?code=abc123&state=xyz456

Before proceeding, always verify the state parameter.

State Validation

if ($_GET['state'] !== $_SESSION['oauth_state']) {
    die('Invalid state');
}

Step 3: Obtain an Access Token

The authorization code must be exchanged for an access token.

Access Token Request

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://www.simosnap.org/rest/service.php/oauth/token',
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'grant_type'    => 'authorization_code',
        'client_id'     => $clientId,
        'client_secret' => $clientSecret,
        'redirect_uri'  => $redirectUri,
        'code'          => $_GET['code']
    ])
]);

$response = curl_exec($ch);

curl_close($ch);

$data = json_decode($response, true);

Typical Response

{
    "access_token": "xxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 3600
}
Documentation: https://www.simosnap.org/resources#oauth