¶ GenAuth - Python SDK OAuth2.0 module

OAuth is an open web standard for authorization, and the current version is 2.0.

Parameters when initializing AuthenticationClient:

• app_id <str> Application ID, required.

• secret <str> Application secret key, required.

• app_host <str> Full application address, such as https://sample-app.genauth.ai, without the last slash '/'.

• redirect_uri <str> Business callback URL, required. For details, please see [Document](/guides/federation/oauth.html#Authorization Code Mode).

• protocol <str> Protocol type, optional values ​​are oidc, oauth, saml, cas, fill in oauth here.

• token_endpoint_auth_method <str> Get token endpoint verification method, optional values ​​are client_secret_post, client_secret_basic, none, default is client_secret_post.

• introspection_endpoint_auth_method <str> Verify token endpoint verification method, optional values ​​are client_secret_post, client_secret_basic, none, default is client_secret_post.

• revocation_endpoint_auth_method <str> Withdraw token endpoint verification method, optional values ​​are client_secret_post, client_secret_basic, none, default is client_secret_post.

¶ Example python from genauth.v2.authentication import AuthenticationClient, AuthenticationClientOptions authentication_client = AuthenticationClient options=AuthenticationClientOptions( app_id='GEN_AUTH_APP_ID', app_host='https://YOUR_DOMAIN.genauth.ai', secret='GEN_AUTH_APP_SECRET', protocol='oauth', ))

¶ Generate a user login link for the OAuth 2.0 protocol

def build_authorize_url(
  self,
  redirect_uri=None,
  response_type=None,
  response_mode=None,
  state=None,
  nonce=None,
  scope=None,
  code_challenge_method=None,
  code_challenge=None,
):
  pass

Generate a user login link for the OAuth 2.0 protocol. Users can access the online login page of GenAuth through this link.

¶ Parameters

Parameters that need to be filled in when initiating authorized login. For details, see Using OAuth2.0 Authorization Code Mode.

• scope <str> Requested permission items, optional, the default value for the OAuth 2.0 protocol is user.

• state <str> Random string, optional, automatically generated by default.

• response_type <str> Response type, optional, optional values ​​are code, token, default is code, authorization code mode.

• redirect_uri <str> Callback address, optional, default is the redirect_uri parameter when the SDK is initialized.

¶ Example python from genauth.v2.authentication import AuthenticationClient, AuthenticationClientOptions authentication_client = AuthenticationClient options=AuthenticationClientOptions( app_id='GEN_AUTH_APP_ID', app_host='https://YOUR_DOMAIN.genauth.ai', secret='GEN_AUTH_APP_SECRET', protocol='oauth', redirect_uri='http://localhost:3000', )) url = authentication_client.build_authorize_url( scope: 'user' ) ### Sample data

https://oidc1.genauth.ai/oauth/auth?state=7400704296715694&scope=user&client_id=5f17a529f64fb009b794a2ff&redirect_uri=https%3A%2F%2Fbaidu.com&response_type=code

¶ Code to Token

def get_access_token_by_code(self, code):
pass

Use the authorization code Code to obtain the user's Token information.

¶ Parameters

• code <str> Authorization code Code. After the user successfully authenticates, GenAuth will send the authorization code Code to the callback address. For details, please see Using OAuth 2.0 Authorization Code Mode. Each Code can only be used once.

¶ Example

When initializing AuthenticationClient, you need to set protocol to oauth.

python from genauth.v2.authentication import AuthenticationClient, AuthenticationClientOptions authentication_client = AuthenticationClient options=AuthenticationClientOptions( app_id='GEN_AUTH_APP_ID', app_host='https://YOUR_DOMAIN.genauth.ai', secret='GEN_AUTH_APP_SECRET', protocol='oauth', )) code = 'xxxx' data = authentication_client.get_access_token_by_code( code=code ) ### Sample data ```json { "access_token": "fa9d2bdd914ea01aa4e434c12d4f919d749fc75c", "token_type": "Bearer", "expires_in": 1209599, "refresh_token": "b5e0e1afe793c6634495434afc262b88ddee9af3", "scope": "user" }

Field explanation:

| Field name | Meaning |
| ------------ | ----------------------------------------- |
| token_type | Token type, fixed value Bearer |
| scope | Authorization scope, authorized user permission items |
| expires_in | Access token expiration time |
| access_token | Access token, Access token issued by GenAuth |

## Token exchange user information

```python
def get_user_info_by_access_token(self, access_token):
pass

Use Access token to obtain user information.

¶ Parameters

• access_token <str> Access token, the content of the Access token exchanged with the authorization code Code. For more information, see Using OIDC Authorization Code Mode.

¶ Example

from genauth.v2.authentication import AuthenticationClient, AuthenticationClientOptions

authentication_client = AuthenticationClient
options=AuthenticationClientOptions(
app_id='GEN_AUTH_APP_ID',
app_host='https://YOUR_DOMAIN.genauth.ai',
secret='GEN_AUTH_APP_SECRET',
protocol='oauth',
))
data = authentication_client.get_user_info_by_access_token('Access token');

¶ Example data

{
  "address": {
    "country": null,
    "postal_code": null,
    "region": null,
    "formatted": null
  },
  "birthdate": null,
  "family_name": null,
  "gender": "U",
  "given_name": null,
  "locale": null,
  "middle_name": null,
  "name": null,
  "nickname": null,
  "picture": "https://files.authing.co/authing-console/default-user-avatar.png",
  "preferred_username": null,
  "profile": null,
  "updated_at": "2021-03-03T06:17:14.485Z",
  "website": null,
  "zoneinfo": null,
  "email": "test1@genauth.ai",
  "email_verified": false,
  "sub": "603f184cec4505e2868431fc", // Abbreviation of subject, which is the user ID
  "phone_number": null,
  "phone_number_verified": false
}

Field explanation:

¶ Refresh Access Token

def get_new_access_token_by_refresh_token(self, refresh_token):
pass

Use Refresh token to get a new Access token.

¶ Parameters

• refresh_token <str> Refresh token, which can be obtained from refresh_token in the return value of get_access_token_by_code method.

¶ Example python from genauth.v2.authentication import AuthenticationClient, AuthenticationClientOptions authentication_client = AuthenticationClient options=AuthenticationClientOptions( app_id='GEN_AUTH_APP_ID', app_host='https://YOUR_DOMAIN.genauth.ai', secret='GEN_AUTH_APP_SECRET', protocol='oauth', )) data = authentication_client.get_new_access_token_by_refresh_token('Refresh Token'); ### Sample data ```json { "access_token": "fa9d2bdd914ea01aa4e434c12d4f919d749fc75c", "token_type": "Bearer", "expires_in": 1209599, "refresh_token": "b5e0e1afe793c6634495434afc262b88ddee9af3",

"scope": "user" }

## Check Access token or Refresh Token

```python
def introspect_token(self, token):
pass

Check the status of Access Token or Refresh Token.

¶ Parameters

• token <str> Access token or Refresh token, which can be obtained from access_token, refresh_token in the return value of get_access_token_by_code method.

¶ Example

from genauth.v2.authentication import AuthenticationClient, AuthenticationClientOptions

authentication_client = AuthenticationClient
options=AuthenticationClientOptions(
app_id='GEN_AUTH_APP_ID',
app_host='https://YOUR_DOMAIN.genauth.ai',
secret='GEN_AUTH_APP_SECRET',
protocol='oauth',
))

data = authentication_client.introspect_token('Access Token');

¶ Example data

Token is returned when it is valid:

{
  "active": true,
  "sub": "5f719946524ee1099229496b", // abbreviation of subject, which is user ID
  "client_id": "5f17a529f64fb009b794a2ff",
  "exp": 1619083024,
  "iat": 1617873424,
  "iss": "https://core.genauth.ai/oauth",
  "jti": "qbovGK-HZL0O_20wY7uXj",
  "scope": "user",
  "token_type": "Bearer"
}

Token is invalid and returns:

{
  "active": false
}

An error will be thrown if the verification process fails.

¶ Revoke Access Token or Refresh token

def revoke_token(self, token):
pass

Revoke Access token or Refresh token. The holder of Access token or Refresh token can notify GenAuth that the token is no longer needed and hope that GenAuth will revoke it.

¶ Parameters

• token <str> Access token or Refresh token, which can be obtained from access_token, refresh_token in the return value of get_access_token_by_code method.

¶ Example

data = authentication_client.revoke_token('Access token or Refresh token');

¶ Example data

Return true when the revocation is successful.

Throws an error when the revocation fails.

¶ Concatenate the logout URL

def build_logout_url(self, redirect_uri=None):
pass

Concatenate the logout URL, users can log out through this link.

¶ Parameters

• redirect_uri <str> The redirection address after logout.

¶ Example

from genauth.v2.authentication import AuthenticationClient, AuthenticationClientOptions

authentication_client = AuthenticationClient
  options=AuthenticationClientOptions(
    app_id='GEN_AUTH_APP_ID',
    app_host='https://YOUR_DOMAIN.genauth.ai',
    secret='GEN_AUTH_APP_SECRET',
    protocol='oauth',
))
url = authentication_client.build_logout_url(
  redirect_uri="http://localhost:3000"
);