From 379e1764ed55f63601e6f2ebc1c7cca0d7ae5b12 Mon Sep 17 00:00:00 2001 From: Marcos Pereira Jr Date: Thu, 15 Feb 2024 21:56:47 -0300 Subject: [PATCH] feat: new docs. --- docs/source/getting_started.rst | 11 +- docs/source/modules/admin.rst | 196 ++++++++++++++++++++++++++ docs/source/modules/openid_client.rst | 146 +++++++++++++++++++ docs/source/modules/uma.rst | 60 ++++++++ 4 files changed, 412 insertions(+), 1 deletion(-) create mode 100644 docs/source/modules/admin.rst create mode 100644 docs/source/modules/openid_client.rst create mode 100644 docs/source/modules/uma.rst diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index b958b9a..936ac8a 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -1,4 +1,13 @@ .. _getting_started: -The User Guide +Quickstart ======================== + +Some examples of using OpenID, Admin and UMA integration. + +.. toctree:: + :maxdepth: 2 + + modules/openid_client + modules/admin + modules/uma diff --git a/docs/source/modules/admin.rst b/docs/source/modules/admin.rst new file mode 100644 index 0000000..3c88c96 --- /dev/null +++ b/docs/source/modules/admin.rst @@ -0,0 +1,196 @@ +.. admin: + +Admin Client +======================== + + +Configure admin client +------------------------- + +.. code-block:: python + + + admin = KeycloakAdmin( + server_url="http://localhost:8080/", + username='example-admin', + password='secret', + realm_name="master", + user_realm_name="only_if_other_realm_than_master") + + +Configure admin client with connection +-------------------------------------------------- + +.. code-block:: python + + from keycloak import KeycloakAdmin + from keycloak import KeycloakOpenIDConnection + + keycloak_connection = KeycloakOpenIDConnection( + server_url="http://localhost:8080/", + username='example-admin', + password='secret', + realm_name="master", + user_realm_name="only_if_other_realm_than_master", + client_id="my_client", + client_secret_key="client-secret", + verify=True) + + keycloak_admin = KeycloakAdmin(connection=keycloak_connection) + + +Create user +------------------------- + +.. code-block:: python + + new_user = keycloak_admin.create_user({"email": "example@example.com", + "username": "example@example.com", + "enabled": True, + "firstName": "Example", + "lastName": "Example"}) + + +Add user and raise exception if username already exists +----------------------------------------------------------- + +The exist_ok currently defaults to True for backwards compatibility reasons. + +.. code-block:: python + + new_user = keycloak_admin.create_user({"email": "example@example.com", + "username": "example@example.com", + "enabled": True, + "firstName": "Example", + "lastName": "Example"}, + exist_ok=False) + +Add user and set password +--------------------------- + +.. code-block:: python + + new_user = keycloak_admin.create_user({"email": "example@example.com", + "username": "example@example.com", + "enabled": True, + "firstName": "Example", + "lastName": "Example", + "credentials": [{"value": "secret","type": "password",}]}) + + +Add user and specify a locale +------------------------------ + +.. code-block:: python + + new_user = keycloak_admin.create_user({"email": "example@example.fr", + "username": "example@example.fr", + "enabled": True, + "firstName": "Example", + "lastName": "Example", + "attributes": { + "locale": ["fr"] + }}) + +User counter +------------------------------ + +.. code-block:: python + + count_users = keycloak_admin.users_count() + +Get users Returns a list of users, filtered according to query parameters +---------------------------------------------------------------------------- + +.. code-block:: python + + users = keycloak_admin.get_users({}) + +Get user ID from username +------------------------------ + +.. code-block:: python + + user_id_keycloak = keycloak_admin.get_user_id("username-keycloak") + + +Get user +------------------------------ + +.. code-block:: python + + user = keycloak_admin.get_user("user-id-keycloak") + +Update user +------------------------------ + +.. code-block:: python + + response = keycloak_admin.update_user(user_id="user-id-keycloak", + payload={'firstName': 'Example Update'}) + + +Update user password +------------------------------ + +.. code-block:: python + + response = keycloak_admin.set_user_password(user_id="user-id-keycloak", password="secret", temporary=True) + + +Get user credentials +------------------------------ + +.. code-block:: python + + credentials = keycloak_admin.get_credentials(user_id='user_id') + +Get user credential by ID +------------------------------ + +.. code-block:: python + + credential = keycloak_admin.get_credential(user_id='user_id', credential_id='credential_id') + +Delete user credential +------------------------------ + +.. code-block:: python + + response = keycloak_admin.delete_credential(user_id='user_id', credential_id='credential_id') + +Delete User +------------------------------ + +.. code-block:: python + + response = keycloak_admin.delete_user(user_id="user-id-keycloak") + +Get consents granted by the user +-------------------------------- + +.. code-block:: python + + consents = keycloak_admin.consents_user(user_id="user-id-keycloak") + +Send user action +------------------------------ + +.. code-block:: python + + response = keycloak_admin.send_update_account(user_id="user-id-keycloak", + payload=['UPDATE_PASSWORD']) + +Send verify email +------------------------------ + +.. code-block:: python + + response = keycloak_admin.send_verify_email(user_id="user-id-keycloak") + +Get sessions associated with the user +-------------------------------------- + +.. code-block:: python + + sessions = keycloak_admin.get_sessions(user_id="user-id-keycloak") diff --git a/docs/source/modules/openid_client.rst b/docs/source/modules/openid_client.rst new file mode 100644 index 0000000..265bf55 --- /dev/null +++ b/docs/source/modules/openid_client.rst @@ -0,0 +1,146 @@ +.. _openid_client: + + +OpenID Client +======================== + +Configure client OpenID +------------------------- + +.. code-block:: python + + from keycloak import KeycloakOpenID + + # Configure client + keycloak_openid = KeycloakOpenID(server_url="http://localhost:8080/auth/", + client_id="example_client", + realm_name="example_realm", + client_secret_key="secret") + + +Get .well_know +----------------------- + +.. code-block:: python + + config_well_known = keycloak_openid.well_known() + + +Get code with OAuth authorization request +---------------------------------------------- + +.. code-block:: python + + auth_url = keycloak_openid.auth_url( + redirect_uri="your_call_back_url", + scope="email", + state="your_state_info") + + +Get access token with code +---------------------------------------------- + +.. code-block:: python + + access_token = keycloak_openid.token( + grant_type='authorization_code', + code='the_code_you_get_from_auth_url_callback', + redirect_uri="your_call_back_url") + + +Get access token with user and password +---------------------------------------------- + +.. code-block:: python + + token = keycloak_openid.token("user", "password") + token = keycloak_openid.token("user", "password", totp="012345") + + +Get token using Token Exchange +---------------------------------------------- + +.. code-block:: python + + token = keycloak_openid.exchange_token(token['access_token'], + "my_client", "other_client", "some_user") + + +Refresh token +---------------------------------------------- + +.. code-block:: python + + token = keycloak_openid.refresh_token(token['refresh_token']) + +Get UserInfo +---------------------------------------------- + +.. code-block:: python + + userinfo = keycloak_openid.userinfo(token['access_token']) + +Logout +---------------------------------------------- + +.. code-block:: python + + keycloak_openid.logout(token['refresh_token']) + +Get certs +---------------------------------------------- + +.. code-block:: python + + certs = keycloak_openid.certs() + +Introspect RPT +---------------------------------------------- + +.. code-block:: python + + token_rpt_info = keycloak_openid.introspect(keycloak_openid.introspect(token['access_token'], + rpt=rpt['rpt'], + token_type_hint="requesting_party_token")) + +Introspect token +---------------------------------------------- + +.. code-block:: python + + token_info = keycloak_openid.introspect(token['access_token']) + + +Decode token +---------------------------------------------- + +.. code-block:: python + + KEYCLOAK_PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\n" + keycloak_openid.public_key() + "\n-----END PUBLIC KEY-----" + options = {"verify_signature": True, "verify_aud": True, "verify_exp": True} + token_info = keycloak_openid.decode_token(token['access_token'], key=KEYCLOAK_PUBLIC_KEY, options=options) + + +Get UMA-permissions by token +---------------------------------------------- + +.. code-block:: python + + token = keycloak_openid.token("user", "password") + permissions = keycloak_openid.uma_permissions(token['access_token']) + +Get UMA-permissions by token with specific resource and scope requested +-------------------------------------------------------------------------- + +.. code-block:: python + + token = keycloak_openid.token("user", "password") + permissions = keycloak_openid.uma_permissions(token['access_token'], permissions="Resource#Scope") + +Get auth status for a specific resource and scope by token +-------------------------------------------------------------------------- + +.. code-block:: python + + token = keycloak_openid.token("user", "password") + auth_status = keycloak_openid.has_uma_access(token['access_token'], "Resource#Scope") diff --git a/docs/source/modules/uma.rst b/docs/source/modules/uma.rst new file mode 100644 index 0000000..c0867a0 --- /dev/null +++ b/docs/source/modules/uma.rst @@ -0,0 +1,60 @@ +.. _uma: + +UMA +======================== + + +Configure client UMA +------------------------- + +.. code-block:: python + + from keycloak import KeycloakOpenIDConnection + from keycloak import KeycloakUMA + + keycloak_connection = KeycloakOpenIDConnection( + server_url="http://localhost:8080/", + realm_name="master", + client_id="my_client", + client_secret_key="client-secret") + + keycloak_uma = KeycloakUMA(connection=keycloak_connection) + + +Create a resource set +------------------------- + +.. code-block:: python + + resource_set = keycloak_uma.resource_set_create({ + "name": "example_resource", + "scopes": ["example:read", "example:write"], + "type": "urn:example"}) + +List resource sets +------------------------- + +.. code-block:: python + + resource_sets = uma.resource_set_list() + +Get resource set +------------------------- + +.. code-block:: python + + latest_resource = uma.resource_set_read(resource_set["_id"]) + +Update resource set +------------------------- + +.. code-block:: python + + latest_resource["name"] = "New Resource Name" + uma.resource_set_update(resource_set["_id"], latest_resource) + +Delete resource set +------------------------ +.. code-block:: python + + uma.resource_set_delete(resource_id=resource_set["_id"])