Welcome to Python Keycloak Client’s documentation!¶

The Python Keycloak Client is a set of API clients written in Python to communicate with the different API’s which are exposed by Keycloak.

Installation¶

$ pip install python-keycloak-client

Async¶

$ pip install python-keycloak-client[aio]

Preparation¶

Make sure you have created a REALM and Client in Keycloak.

Usage¶

Everything starts with an instance of keycloak.realm.KeycloakRealm

from keycloak.realm import KeycloakRealm

realm = KeycloakRealm(server_url='https://example.com', realm_name='my_realm')

from keycloak.aio.realm import KeycloakRealm


async def main(loop=None):
    realm_params = dict(
        server_url='https://example.com',
        realm_name='my_realm',
        loop=loop
    )
    async with KeycloakRealm(**realm_params) as realm:
        # do something
        print(realm.realm_name)

if __name__ == '__main__':
    import asyncio

    loop = asyncio.get_event_loop()
    loop.run_until_complete(main(loop))

OpenID Connect¶

The OpenID Connect entry point can be retrieved from the realm object.

from keycloak.realm import KeycloakRealm

realm = KeycloakRealm(server_url='https://example.com', realm_name='my_realm')

oidc_client = realm.open_id_connect(client_id='my-client',
                                    client_secret='very-secret-client-secret')

Async¶

from keycloak.aio.realm import KeycloakRealm


async def main(loop=None):
    realm_params = dict(
        server_url='https://example.com',
        realm_name='my_realm',
        loop=loop
    )
    async with KeycloakRealm(**realm_params) as realm:
        oidc_client = await realm.open_id_connect(
            client_id='my-client',
            client_secret='very-secret-client-secret'
        )
        # do something


if __name__ == '__main__':
    import asyncio

    loop = asyncio.get_event_loop()
    loop.run_until_complete(main(loop))

KeycloakOpenidConnect.decode_token(token, key, algorithms=None, **kwargs)¶

A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. This specification also defines a JWK Set JSON data structure that represents a set of JWKs. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries established by that specification.

https://tools.ietf.org/html/rfc7517

Parameters:	token (str) – A signed JWS to be verified. key (str) – A key to attempt to verify the payload with. algorithms (str,list) – (optional) Valid algorithms that should be used to verify the JWS. Defaults to [‘RS256’] audience (str) – (optional) The intended audience of the token. If the “aud” claim is included in the claim set, then the audience must be included and must equal the provided claim. issuer (str,iterable) – (optional) Acceptable value(s) for the issuer of the token. If the “iss” claim is included in the claim set, then the issuer must be given and the claim in the token must be among the acceptable values. subject (str) – (optional) The subject of the token. If the “sub” claim is included in the claim set, then the subject must be included and must equal the provided claim. access_token (str) – (optional) An access token returned alongside the id_token during the authorization grant flow. If the “at_hash” claim is included in the claim set, then the access_token must be included, and it must match the “at_hash” claim. options (dict) – (optional) A dictionary of options for skipping validation steps. defaults: { 'verify_signature': True, 'verify_aud': True, 'verify_iat': True, 'verify_exp': True, 'verify_nbf': True, 'verify_iss': True, 'verify_sub': True, 'verify_jti': True, 'leeway': 0, }
Returns:	The dict representation of the claims set, assuming the signature is valid and all requested data validation passes.
Return type:	dict
Raises:	jose.exceptions.JWTError – If the signature is invalid in any way. jose.exceptions.ExpiredSignatureError – If the signature has expired. jose.exceptions.JWTClaimsError – If any claim is invalid in any way.

KeycloakOpenidConnect.authorization_url(**kwargs)¶

Get authorization URL to redirect the resource owner to.

https://tools.ietf.org/html/rfc6749#section-4.1.1

Parameters:	redirect_uri (str) – (optional) Absolute URL of the client where the user-agent will be redirected to. scope (str) – (optional) Space delimited list of strings. state (str) – (optional) An opaque value used by the client to maintain state between the request and callback
Returns:	URL to redirect the resource owner to
Return type:	str

KeycloakOpenidConnect.authorization_code(code, redirect_uri)¶

Retrieve access token by authorization_code grant.

https://tools.ietf.org/html/rfc6749#section-4.1.3

Parameters:	code (str) – The authorization code received from the authorization server. redirect_uri (str) – the identical value of the “redirect_uri” parameter in the authorization request.
Return type:	dict
Returns:	Access token response

KeycloakOpenidConnect.client_credentials(**kwargs)¶

Retrieve access token by client_credentials grant.

https://tools.ietf.org/html/rfc6749#section-4.4

Parameters:	scope (str) – (optional) Space delimited list of strings.
Return type:	dict
Returns:	Access token response

KeycloakOpenidConnect.refresh_token(refresh_token, **kwargs)¶

Refresh an access token

https://tools.ietf.org/html/rfc6749#section-6

Parameters:	refresh_token (str) – scope (str) – (optional) Space delimited list of strings.
Return type:	dict
Returns:	Access token response

KeycloakOpenidConnect.logout(refresh_token)¶

The logout endpoint logs out the authenticated user.

Parameters:	refresh_token (str) –

KeycloakOpenidConnect.certs()¶

The certificate endpoint returns the public keys enabled by the realm, encoded as a JSON Web Key (JWK). Depending on the realm settings there can be one or more keys enabled for verifying tokens.

https://tools.ietf.org/html/rfc7517

Return type:	dict

KeycloakOpenidConnect.userinfo(token)¶

The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns Claims about the authenticated End-User. To obtain the requested Claims about the End-User, the Client makes a request to the UserInfo Endpoint using an Access Token obtained through OpenID Connect Authentication. These Claims are normally represented by a JSON object that contains a collection of name and value pairs for the Claims.

http://openid.net/specs/openid-connect-core-1_0.html#UserInfo

Parameters:	token (str) –
Return type:	dict

KeycloakOpenidConnect.token_exchange(**kwargs)¶

Token exchange is the process of using a set of credentials or token to obtain an entirely different token.

http://www.keycloak.org/docs/latest/securing_apps/index.html #_token-exchange https://www.ietf.org/id/draft-ietf-oauth-token-exchange-12.txt

Parameters:	subject_token – A security token that represents the identity of the party on behalf of whom the request is being made. It is required if you are exchanging an existing token for a new one. subject_issuer – Identifies the issuer of the subject_token. It can be left blank if the token comes from the current realm or if the issuer can be determined from the subject_token_type. Otherwise it is required to be specified. Valid values are the alias of an Identity Provider configured for your realm. Or an issuer claim identifier configured by a specific Identity Provider. subject_token_type – This parameter is the type of the token passed with the subject_token parameter. This defaults to urn:ietf:params:oauth:token-type:access_token if the subject_token comes from the realm and is an access token. If it is an external token, this parameter may or may not have to be specified depending on the requirements of the subject_issuer. requested_token_type – This parameter represents the type of token the client wants to exchange for. Currently only oauth and OpenID Connect token types are supported. The default value for this depends on whether the is urn:ietf:params:oauth:token-type:refresh_token in which case you will be returned both an access token and refresh token within the response. Other appropriate values are urn:ietf:params:oauth:token-type:access_token and urn:ietf:params:oauth:token-type:id_token audience – This parameter specifies the target client you want the new token minted for. requested_issuer – This parameter specifies that the client wants a token minted by an external provider. It must be the alias of an Identity Provider configured within the realm. requested_subject – This specifies a username or user id if your client wants to impersonate a different user.
Return type:	dict
Returns:	access_token, refresh_token and expires_in

Authz (Authorization services)¶

The Authz client can be retrieved from the realm object.

from keycloak.realm import KeycloakRealm

realm = KeycloakRealm(server_url='https://example.com', realm_name='my_realm')

authz_client = realm.authz(client_id='my-client')

Async¶

from keycloak.aio.realm import KeycloakRealm


async def main(loop=None):
    realm_params = dict(
        server_url='https://example.com',
        realm_name='my_realm',
        loop=loop
    )
    async with KeycloakRealm(**realm_params) as realm:
        authz_client = await realm.authz(client_id='my-client')
        # do something


if __name__ == '__main__':
    import asyncio

    loop = asyncio.get_event_loop()
    loop.run_until_complete(main(loop))

KeycloakAuthz.entitlement(token)¶

Client applications can use a specific endpoint to obtain a special security token called a requesting party token (RPT). This token consists of all the entitlements (or permissions) for a user as a result of the evaluation of the permissions and authorization policies associated with the resources being requested. With an RPT, client applications can gain access to protected resources at the resource server.

http://www.keycloak.org/docs/latest/authorization_services/index .html#_service_entitlement_api

Return type:	dict

Admin API¶

Manage Realms, Clients, Roles, Users etc.

http://www.keycloak.org/docs-api/3.4/rest-api/index.html

The admin API client get be retrieved from the realm object.

from keycloak.realm import KeycloakRealm

realm = KeycloakRealm(server_url='https://example.com', realm_name='my_realm')

admin_client = realm.admin

Async¶

from keycloak.aio.realm import KeycloakRealm


async def main(loop=None):
    realm_params = dict(
        server_url='https://example.com',
        realm_name='my_realm',
        loop=loop
    )
    async with KeycloakRealm(**realm_params) as realm:
        admin_client = realm.admin
        # do something


if __name__ == '__main__':
    import asyncio

    loop = asyncio.get_event_loop()
    loop.run_until_complete(main(loop))

Realms¶

Currently there is no actual functionality available for Realm management. However this endpoint is the entrypoint for all other clients.

realm = realm.admin.realms.by_name('realm-name')

Clients¶

Manage clients

clients = realm.admin.realms.by_name('realm-name').clients

The following methods can be accessed:

Clients.all()¶

Roles¶

Manage client roles

roles = realm.admin.realms.by_name('realm-name').clients.by_id('#client id').roles

The following methods are available:

Actions on a specific role

role = realm.admin.realms.by_name('realm-name').clients.by_id('#client id').roles.by_name('role-name')

The following methods are available:

Users¶

Manage users in a REALM

users = realm.admin.realms.by_name('realm-name').users

The following methods are available:

Users.create(username, **kwargs)¶

Create a user in Keycloak

http://www.keycloak.org/docs-api/3.4/rest-api/index.html#_users_resource

Parameters:	username (str) – credentials (object) – (optional) first_name (str) – (optional) last_name (str) – (optional) email (str) – (optional) enabled (boolean) – (optional)

UMA (User-Managed Access)¶

The UMA client can be retrieved from the realm object.

http://www.keycloak.org/docs/latest/authorization_services/index.html#_service_overview

from keycloak.realm import KeycloakRealm

realm = KeycloakRealm(server_url='https://example.com', realm_name='my_realm')

uma_client = realm.uma()

Async¶

from keycloak.aio.realm import KeycloakRealm


async def main(loop=None):
    realm_params = dict(
        server_url='https://example.com',
        realm_name='my_realm',
        loop=loop
    )
    async with KeycloakRealm(**realm_params) as realm:
        uma_client = realm.uma()
        # do something


if __name__ == '__main__':
    import asyncio

    loop = asyncio.get_event_loop()
    loop.run_until_complete(main(loop))

Resource Set management¶

KeycloakUMA.resource_set_create(token, name, **kwargs)¶

Create a resource set.

https://docs.kantarainitiative.org/uma/rec-oauth-resource-reg-v1_0_1.html#rfc.section.2.2.1

Parameters:	token (str) – client access token id (str) – Identifier of the resource set name (str) – uri (str) – (optional) type (str) – (optional) scopes (list) – (optional) icon_url (str) – (optional) DisplayName (str) – (optional) ownerManagedAccess (boolean) – (optional) owner (str) – (optional)
Return type:	str

KeycloakUMA.resource_set_update(token, id, name, **kwargs)¶

Update a resource set.

https://docs.kantarainitiative.org/uma/rec-oauth-resource-reg-v1_0_1.html#update-resource-set

Parameters:	token (str) – client access token id (str) – Identifier of the resource set name (str) – uri (str) – (optional) type (str) – (optional) scopes (list) – (optional) icon_url (str) – (optional)
Return type:	str

KeycloakUMA.resource_set_read(token, id)¶

Read a resource set.

https://docs.kantarainitiative.org/uma/rec-oauth-resource-reg-v1_0_1.html#read-resource-set

Parameters:	token (str) – client access token id (str) – Identifier of the resource set
Return type:	dict

KeycloakUMA.resource_set_delete(token, id)¶

Delete a resource set.

https://docs.kantarainitiative.org/uma/rec-oauth-resource-reg-v1_0_1.html#delete-resource-set

Parameters:	token (str) – client access token id (str) – Identifier of the resource set

KeycloakUMA.resource_set_list(token, **kwargs)¶

List a resource set.

https://docs.kantarainitiative.org/uma/rec-oauth-resource-reg-v1_0_1.html#list-resource-sets

Parameters:	token (str) – client access token name (str) – (optional) uri (str) – (optional) owner (str) – (optional) type (str) – (optional) scope (str) – (optional)
Return type:	list

Welcome to Python Keycloak Client’s documentation!¶

Installation¶

Async¶

Preparation¶

Usage¶

OpenID Connect¶

Async¶

Authz (Authorization services)¶

Async¶

Admin API¶

Async¶

Realms¶

Clients¶

Roles¶

Users¶

UMA (User-Managed Access)¶

Async¶

Resource Set management¶

Indices and tables¶