keycloak.keycloak_openid ======================== .. py:module:: keycloak.keycloak_openid .. autoapi-nested-parse:: Keycloak OpenID module. The module contains mainly the implementation of KeycloakOpenID class, the main class to handle authentication and token manipulation. Classes ------- .. autoapisummary:: keycloak.keycloak_openid.KeycloakOpenID Module Contents --------------- .. py:class:: KeycloakOpenID(server_url: str, realm_name: str, client_id: str, client_secret_key: str | None = None, verify: bool | str = True, custom_headers: dict | None = None, proxies: dict | None = None, timeout: int | None = 60, cert: str | tuple | None = None, max_retries: int = 1, pool_maxsize: int | None = None) Keycloak OpenID client. :param server_url: Keycloak server url :param client_id: client id :param realm_name: realm name :param client_secret_key: client secret key :param verify: Boolean value to enable or disable certificate validation or a string containing a path to a CA bundle to use :param custom_headers: dict of custom header to pass to each HTML request :param proxies: dict of proxies to sent the request by. :param timeout: connection timeout in seconds :param cert: An SSL certificate used by the requested host to authenticate the client. Either a path to an SSL certificate file, or two-tuple of (certificate file, key file). :param max_retries: The total number of times to retry HTTP requests. :param pool_maxsize: The maximum number of connections to save in the pool. :type pool_maxsize: int .. py:property:: client_id :type: str Get client id. :returns: Client id :rtype: str .. py:property:: client_secret_key :type: str | None Get the client secret key. :returns: Client secret key :rtype: str .. py:property:: realm_name :type: str Get the realm name. :returns: Realm name :rtype: str .. py:property:: connection :type: keycloak.connection.ConnectionManager Get connection. :returns: Connection manager object :rtype: ConnectionManager .. py:property:: authorization :type: keycloak.authorization.Authorization Get authorization. :returns: The authorization manager :rtype: Authorization .. py:method:: _add_secret_key(payload: dict) -> dict Add secret key if exists. :param payload: Payload :type payload: dict :returns: Payload with the secret key :rtype: dict .. py:method:: _build_name_role(role: str) -> str Build name of a role. :param role: Role name :type role: str :returns: Role path :rtype: str .. py:method:: _token_info(token: str, method_token_info: str, **kwargs: Any) -> dict Getter for the token data. :param token: Token :type token: str :param method_token_info: Token info method to use :type method_token_info: str :param kwargs: Additional keyword arguments passed to the decode_token method :type kwargs: dict :returns: Token info :rtype: dict .. py:method:: well_known() -> dict Get the well_known object. The most important endpoint to understand is the well-known configuration endpoint. It lists endpoints and other configuration options relevant to the OpenID Connect implementation in Keycloak. :returns: It lists endpoints and other configuration options relevant :rtype: dict .. py:method:: auth_url(redirect_uri: str, scope: str = 'email', state: str = '', nonce: str = '', code_challenge: str | None = None, code_challenge_method: str | None = None) -> str Get authorization URL endpoint. :param redirect_uri: Redirect url to receive oauth code :type redirect_uri: str :param scope: Scope of authorization request, split with the blank space :type scope: str :param state: State will be returned to the redirect_uri :type state: str :param nonce: Associates a Client session with an ID Token to mitigate replay attacks :type nonce: str :param code_challenge: PKCE code challenge :type code_challenge: str :param code_challenge_method: PKCE code challenge method :type code_challenge_method: str :returns: Authorization URL Full Build :rtype: str .. py:method:: token(username: str | None = '', password: str | None = '', grant_type: str = 'password', code: str = '', redirect_uri: str = '', totp: int | None = None, scope: str = 'openid', code_verifier: str | None = None, **extra: Any) -> dict Retrieve user token. The token endpoint is used to obtain tokens. Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used. The token endpoint is also used to obtain new access tokens when they expire. http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint :param username: Username :type username: str :param password: Password :type password: str :param grant_type: Grant type :type grant_type: str :param code: Code :type code: str :param redirect_uri: Redirect URI :type redirect_uri: str :param totp: Time-based one-time password :type totp: int :param scope: Scope, defaults to openid :type scope: str :param code_verifier: PKCE code verifier :type code_verifier: str :param extra: Additional extra arguments :type extra: dict :returns: Keycloak token :rtype: dict .. py:method:: refresh_token(refresh_token: str, grant_type: str = 'refresh_token') -> dict Refresh the user token. The token endpoint is used to obtain tokens. Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used. The token endpoint is also used to obtain new access tokens when they expire. http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint :param refresh_token: Refresh token from Keycloak :type refresh_token: str :param grant_type: Grant type :type grant_type: str :returns: New token :rtype: dict .. py:method:: exchange_token(token: str, audience: str | None = None, subject: str | None = None, subject_token_type: str | None = None, subject_issuer: str | None = None, requested_issuer: str | None = None, requested_token_type: str = 'urn:ietf:params:oauth:token-type:refresh_token', scope: str = 'openid') -> dict Exchange user token. Use a token to obtain an entirely different token. See https://www.keycloak.org/docs/latest/securing_apps/index.html#_token-exchange :param token: Access token :type token: str :param audience: Audience :type audience: str :param subject: Subject :type subject: str :param subject_token_type: Token Type specification :type subject_token_type: Optional[str] :param subject_issuer: Issuer :type subject_issuer: Optional[str] :param requested_issuer: Issuer :type requested_issuer: Optional[str] :param requested_token_type: Token type specification :type requested_token_type: str :param scope: Scope, defaults to openid :type scope: str :returns: Exchanged token :rtype: dict .. py:method:: userinfo(token: str) -> dict | bytes Get the user info object. The userinfo endpoint returns standard claims about the authenticated user, and is protected by a bearer token. http://openid.net/specs/openid-connect-core-1_0.html#UserInfo :param token: Access token :type token: str :returns: Userinfo object :rtype: dict | bytes .. py:method:: logout(refresh_token: str) -> dict Log out the authenticated user. :param refresh_token: Refresh token from Keycloak :type refresh_token: str :returns: Keycloak server response :rtype: dict .. py:method:: certs() -> dict Get certificates. 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 :returns: Certificates :rtype: dict .. py:method:: public_key() -> str Retrieve the public key. The public key is exposed by the realm page directly. :returns: The public key :rtype: str .. py:method:: entitlement(token: str, resource_server_id: str) -> dict Get entitlements from the 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. :param token: Access token :type token: str :param resource_server_id: Resource server ID :type resource_server_id: str :returns: Entitlements :rtype: dict .. py:method:: introspect(token: str, rpt: str | None = None, token_type_hint: str | None = None) -> dict Introspect the user token. The introspection endpoint is used to retrieve the active state of a token. It is can only be invoked by confidential clients. https://tools.ietf.org/html/rfc7662 :param token: Access token :type token: str :param rpt: Requesting party token :type rpt: str :param token_type_hint: Token type hint :type token_type_hint: str :returns: Token info :rtype: dict :raises KeycloakRPTNotFound: In case of RPT not specified .. py:method:: _verify_token(token: str, key: jwcrypto.jwk.JWK | jwcrypto.jwk.JWKSet | None, **kwargs: Any) -> dict :staticmethod: Decode and optionally validate a token. :param token: The token to verify :type token: str :param key: Which key should be used for validation. If not provided, the validation is not performed and the token is implicitly valid. :type key: Union[jwk.JWK, jwk.JWKSet, None] :param kwargs: Additional keyword arguments for jwcrypto's JWT object :type kwargs: dict :returns: Decoded token .. py:method:: decode_token(token: str, validate: bool = True, **kwargs: Any) -> dict Decode user token. 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 :param token: Keycloak token :type token: str :param validate: Determines whether the token should be validated with the public key. Defaults to True. :type validate: bool :param kwargs: Additional keyword arguments for jwcrypto's JWT object :type kwargs: dict :returns: Decoded token :rtype: dict .. py:method:: load_authorization_config(path: str) -> None Load Keycloak settings (authorization). :param path: settings file (json) :type path: str .. py:method:: get_policies(token: str, method_token_info: str = 'introspect', **kwargs: Any) -> list | None Get policies by user token. :param token: User token :type token: str :param method_token_info: Method for token info decoding :type method_token_info: str :param kwargs: Additional keyword arguments :type kwargs: dict :return: Policies :rtype: dict :raises KeycloakAuthorizationConfigError: In case of bad authorization configuration :raises KeycloakInvalidTokenError: In case of bad token .. py:method:: get_permissions(token: str, method_token_info: str = 'introspect', **kwargs: Any) -> list | None Get permission by user token. :param token: user token :type token: str :param method_token_info: Decode token method :type method_token_info: str :param kwargs: parameters for decode :type kwargs: dict :returns: permissions list :rtype: list :raises KeycloakAuthorizationConfigError: In case of bad authorization configuration :raises KeycloakInvalidTokenError: In case of bad token .. py:method:: uma_permissions(token: str, permissions: str | list | dict | tuple | set = '', **extra_payload: Any) -> list Get UMA permissions by user token with requested permissions. The token endpoint is used to retrieve UMA permissions from Keycloak. It can only be invoked by confidential clients. http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint :param token: user token :type token: str :param permissions: list of uma permissions list(resource:scope) requested by the user :type permissions: str :param extra_payload: Additional payload data :type extra_payload: dict :returns: Keycloak server response :rtype: list .. py:method:: has_uma_access(token: str, permissions: str | list | dict | tuple | set) -> keycloak.uma_permissions.AuthStatus Determine whether user has uma permissions with specified user token. :param token: user token :type token: str :param permissions: list of uma permissions (resource:scope) :type permissions: str :return: Authentication status :rtype: AuthStatus :raises KeycloakAuthenticationError: In case of failed authentication :raises KeycloakPostError: In case of failed request to Keycloak .. py:method:: register_client(token: str, payload: dict) -> dict Create a client. ClientRepresentation: https://www.keycloak.org/docs-api/24.0.2/rest-api/index.html#_clientrepresentation :param token: Initial access token :type token: str :param payload: ClientRepresentation :type payload: dict :return: Client Representation :rtype: dict .. py:method:: device(scope: str = '') -> dict Get device authorization grant. The device endpoint is used to obtain a user code verification and user authentication. The response contains a device_code, user_code, verification_uri, verification_uri_complete, expires_in (lifetime in seconds for device_code and user_code), and polling interval. Users can either follow the verification_uri and enter the user_code or follow the verification_uri_complete. After authenticating with valid credentials, users can obtain tokens using the "urn:ietf:params:oauth:grant-type:device_code" grant_type and the device_code. https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow https://github.com/keycloak/keycloak-community/blob/main/design/oauth2-device-authorization-grant.md#how-to-try-it :param scope: Scope of authorization request, split with the blank space :type scope: str :returns: Device Authorization Response :rtype: dict .. py:method:: update_client(token: str, client_id: str, payload: dict) -> dict Update a client. ClientRepresentation: https://www.keycloak.org/docs-api/24.0.2/rest-api/index.html#_clientrepresentation :param token: registration access token :type token: str :param client_id: Keycloak client id :type client_id: str :param payload: ClientRepresentation :type payload: dict :return: Client Representation :rtype: bytes .. py:method:: _a_token_info(token: str, method_token_info: str, **kwargs: Any) -> dict :async: Asynchronous getter for the token data. :param token: Token :type token: str :param method_token_info: Token info method to use :type method_token_info: str :param kwargs: Additional keyword arguments passed to the decode_token method :type kwargs: dict :returns: Token info :rtype: dict .. py:method:: a_well_known() -> dict :async: Get the well_known object asynchronously. The most important endpoint to understand is the well-known configuration endpoint. It lists endpoints and other configuration options relevant to the OpenID Connect implementation in Keycloak. :returns: It lists endpoints and other configuration options relevant :rtype: dict .. py:method:: a_auth_url(redirect_uri: str, scope: str = 'email', state: str = '', nonce: str = '', code_challenge: str | None = None, code_challenge_method: str | None = None) -> str :async: Get authorization URL endpoint asynchronously. :param redirect_uri: Redirect url to receive oauth code :type redirect_uri: str :param scope: Scope of authorization request, split with the blank space :type scope: str :param state: State will be returned to the redirect_uri :type state: str :param nonce: Associates a Client session with an ID Token to mitigate replay attacks :type nonce: str :param code_challenge: PKCE code challenge :type code_challenge: str :param code_challenge_method: PKCE code challenge method :type code_challenge_method: str :returns: Authorization URL Full Build :rtype: str .. py:method:: a_token(username: str | None = '', password: str | None = '', grant_type: str = 'password', code: str = '', redirect_uri: str = '', totp: int | None = None, scope: str = 'openid', code_verifier: str | None = None, **extra: Any) -> dict :async: Retrieve user token asynchronously. The token endpoint is used to obtain tokens. Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used. The token endpoint is also used to obtain new access tokens when they expire. http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint :param username: Username :type username: str :param password: Password :type password: str :param grant_type: Grant type :type grant_type: str :param code: Code :type code: str :param redirect_uri: Redirect URI :type redirect_uri: str :param totp: Time-based one-time password :type totp: int :param scope: Scope, defaults to openid :type scope: str :param code_verifier: PKCE code verifier :type code_verifier: str :param extra: Additional extra arguments :type extra: dict :returns: Keycloak token :rtype: dict .. py:method:: a_refresh_token(refresh_token: str, grant_type: str = 'refresh_token') -> dict :async: Refresh the user token asynchronously. The token endpoint is used to obtain tokens. Tokens can either be obtained by exchanging an authorization code or by supplying credentials directly depending on what flow is used. The token endpoint is also used to obtain new access tokens when they expire. http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint :param refresh_token: Refresh token from Keycloak :type refresh_token: str :param grant_type: Grant type :type grant_type: str :returns: New token :rtype: dict .. py:method:: a_exchange_token(token: str, audience: str | None = None, subject: str | None = None, subject_token_type: str | None = None, subject_issuer: str | None = None, requested_issuer: str | None = None, requested_token_type: str = 'urn:ietf:params:oauth:token-type:refresh_token', scope: str = 'openid') -> dict :async: Exchange user token asynchronously. Use a token to obtain an entirely different token. See https://www.keycloak.org/docs/latest/securing_apps/index.html#_token-exchange :param token: Access token :type token: str :param audience: Audience :type audience: str :param subject: Subject :type subject: str :param subject_token_type: Token Type specification :type subject_token_type: Optional[str] :param subject_issuer: Issuer :type subject_issuer: Optional[str] :param requested_issuer: Issuer :type requested_issuer: Optional[str] :param requested_token_type: Token type specification :type requested_token_type: str :param scope: Scope, defaults to openid :type scope: str :returns: Exchanged token :rtype: dict .. py:method:: a_userinfo(token: str) -> dict | bytes :async: Get the user info object asynchronously. The userinfo endpoint returns standard claims about the authenticated user, and is protected by a bearer token. http://openid.net/specs/openid-connect-core-1_0.html#UserInfo :param token: Access token :type token: str :returns: Userinfo object :rtype: dict | bytes .. py:method:: a_logout(refresh_token: str) -> dict :async: Log out the authenticated user asynchronously. :param refresh_token: Refresh token from Keycloak :type refresh_token: str :returns: Keycloak server response :rtype: dict .. py:method:: a_certs() -> dict :async: Get certificates asynchronously. 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 :returns: Certificates :rtype: dict .. py:method:: a_public_key() -> str :async: Retrieve the public key asynchronously. The public key is exposed by the realm page directly. :returns: The public key :rtype: str .. py:method:: a_entitlement(token: str, resource_server_id: str) -> dict :async: Get entitlements from the token asynchronously. 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. :param token: Access token :type token: str :param resource_server_id: Resource server ID :type resource_server_id: str :returns: Entitlements :rtype: dict .. py:method:: a_introspect(token: str, rpt: str | None = None, token_type_hint: str | None = None) -> dict :async: Introspect the user token asynchronously. The introspection endpoint is used to retrieve the active state of a token. It is can only be invoked by confidential clients. https://tools.ietf.org/html/rfc7662 :param token: Access token :type token: str :param rpt: Requesting party token :type rpt: str :param token_type_hint: Token type hint :type token_type_hint: str :returns: Token info :rtype: dict :raises KeycloakRPTNotFound: In case of RPT not specified .. py:method:: a_decode_token(token: str, validate: bool = True, **kwargs: Any) -> dict :async: Decode user token asynchronously. 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 :param token: Keycloak token :type token: str :param validate: Determines whether the token should be validated with the public key. Defaults to True. :type validate: bool :param kwargs: Additional keyword arguments for jwcrypto's JWT object :type kwargs: dict :returns: Decoded token :rtype: dict .. py:method:: a_load_authorization_config(path: str) -> None :async: Load Keycloak settings (authorization) asynchronously. :param path: settings file (json) :type path: str .. py:method:: a_get_policies(token: str, method_token_info: str = 'introspect', **kwargs: Any) -> list | None :async: Get policies by user token asynchronously. :param token: User token :type token: str :param method_token_info: Method for token info decoding :type method_token_info: str :param kwargs: Additional keyword arguments :type kwargs: dict :return: Policies :rtype: list | None :raises KeycloakAuthorizationConfigError: In case of bad authorization configuration :raises KeycloakInvalidTokenError: In case of bad token .. py:method:: a_get_permissions(token: str, method_token_info: str = 'introspect', **kwargs: Any) -> list | None :async: Get permission by user token asynchronously. :param token: user token :type token: str :param method_token_info: Decode token method :type method_token_info: str :param kwargs: parameters for decode :type kwargs: dict :returns: permissions list :rtype: list | None :raises KeycloakAuthorizationConfigError: In case of bad authorization configuration :raises KeycloakInvalidTokenError: In case of bad token .. py:method:: a_uma_permissions(token: str, permissions: str | list | dict | tuple | set = '', **extra_payload: Any) -> list :async: Get UMA permissions by user token with requested permissions asynchronously. The token endpoint is used to retrieve UMA permissions from Keycloak. It can only be invoked by confidential clients. http://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint :param token: user token :type token: str :param permissions: list of uma permissions list(resource:scope) requested by the user :type permissions: str :param extra_payload: Additional payload data :type extra_payload: dict :returns: Keycloak server response :rtype: list .. py:method:: a_has_uma_access(token: str, permissions: str | list | dict | tuple | set) -> keycloak.uma_permissions.AuthStatus :async: Determine whether user has uma permissions with specified user token asynchronously. :param token: user token :type token: str :param permissions: list of uma permissions (resource:scope) :type permissions: str :return: Authentication status :rtype: AuthStatus :raises KeycloakAuthenticationError: In case of failed authentication :raises KeycloakPostError: In case of failed request to Keycloak .. py:method:: a_register_client(token: str, payload: dict) -> dict :async: Create a client asynchronously. ClientRepresentation: https://www.keycloak.org/docs-api/24.0.2/rest-api/index.html#_clientrepresentation :param token: Initial access token :type token: str :param payload: ClientRepresentation :type payload: dict :return: Client Representation :rtype: dict .. py:method:: a_device(scope: str = '') -> dict :async: Get device authorization grant asynchronously. The device endpoint is used to obtain a user code verification and user authentication. The response contains a device_code, user_code, verification_uri, verification_uri_complete, expires_in (lifetime in seconds for device_code and user_code), and polling interval. Users can either follow the verification_uri and enter the user_code or follow the verification_uri_complete. After authenticating with valid credentials, users can obtain tokens using the "urn:ietf:params:oauth:grant-type:device_code" grant_type and the device_code. https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow https://github.com/keycloak/keycloak-community/blob/main/design/oauth2-device-authorization-grant.md#how-to-try-it :param scope: Scope of authorization request, split with the blank space :type scope: str :returns: Device Authorization Response :rtype: dict .. py:method:: a_update_client(token: str, client_id: str, payload: dict) -> dict :async: Update a client asynchronously. ClientRepresentation: https://www.keycloak.org/docs-api/24.0.2/rest-api/index.html#_clientrepresentation :param token: registration access token :type token: str :param client_id: Keycloak client id :type client_id: str :param payload: ClientRepresentation :type payload: dict :return: Client Representation :rtype: dict