feat: new docs.

2 years ago · 02de374a22
4 changed files with 412 additions and 1 deletions
--- 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
--- a/docs/source/modules/admin.rst
+++ 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")
--- a/docs/source/modules/openid_client.rst
+++ 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")
--- a/docs/source/modules/uma.rst
+++ 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"])