ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
Code Releases Activity

Add keycloak_authz_custom_policy module (#7126)

Browse source 
* Add keycloak_authz_custom_policy module

* keycloak.py: add linefeed to keep linter happy

* keycloak_authz_custom_policy: add basic integration tests

* keycloak_authz_custom_policy: add support for check_mode

* keycloak_authz_custom_policy: add check_mode-specific integration tests

Signed-off-by: Samuli Seppänen <samuli.seppanen@puppeteers.net>

* keycloak_authz_custom_policy: improve logging

Signed-off-by: Samuli Seppänen <samuli.seppanen@puppeteers.net>

* keycloak_authz_custom_policy: fix typo

* keycloak_authz_custom_policy: add licensing information

This should make this module REUSE compliant

* keycloak_authz_custom_policy: remove comment markers from license files

* keycloak_authz_custom_policy: fix typo in the example

* keycloak_authz_custom_policy: fix typos in metadata

* keycloak_authz_custom_policy: change version_added to 7.5.0

* Update plugins/modules/keycloak_authz_custom_policy.py

Co-authored-by: Felix Fontein <felix@fontein.de>

---------

Signed-off-by: Samuli Seppänen <samuli.seppanen@puppeteers.net>
Co-authored-by: Felix Fontein <felix@fontein.de>
This commit is contained in:
Samuli Seppänen 2023-09-19 19:07:25 +03:00 committed by GitHub
parent b38423c059
commit 721108d92e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
17 changed files with 485 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.github/BOTMETA.yml vendored
View file

@ -703,6 +703,8 @@ files:
maintainers: mattock
$modules/keycloak_authz_permission.py:
maintainers: mattock
$modules/keycloak_authz_custom_policy.py:
maintainers: mattock
$modules/keycloak_authz_permission_info.py:
maintainers: mattock
$modules/keycloak_client_rolemapping.py:

24
plugins/module_utils/identity/keycloak/keycloak.py
View file

@ -116,6 +116,9 @@ URL_AUTHZ_PERMISSIONS = "{url}/admin/realms/{realm}/clients/{client_id}/authz/re
URL_AUTHZ_RESOURCES = "{url}/admin/realms/{realm}/clients/{client_id}/authz/resource-server/resource"
URL_AUTHZ_CUSTOM_POLICY = "{url}/admin/realms/{realm}/clients/{client_id}/authz/resource-server/policy/{policy_type}"
URL_AUTHZ_CUSTOM_POLICIES = "{url}/admin/realms/{realm}/clients/{client_id}/authz/resource-server/policy"
def keycloak_argument_spec():
"""
@ -2922,6 +2925,27 @@ class KeycloakAPI(object):
list_of_groups.append(group_dict)
return list_of_groups
def create_authz_custom_policy(self, policy_type, payload, client_id, realm):
"""Create a custom policy for a Keycloak client"""
url = URL_AUTHZ_CUSTOM_POLICY.format(url=self.baseurl, policy_type=policy_type, client_id=client_id, realm=realm)
try:
return open_url(url, method='POST', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
data=json.dumps(payload), validate_certs=self.validate_certs)
except Exception as e:
self.module.fail_json(msg='Could not create permission %s for client %s in realm %s: %s' % (payload['name'], client_id, realm, str(e)))
def remove_authz_custom_policy(self, policy_id, client_id, realm):
"""Remove a custom policy from a Keycloak client"""
url = URL_AUTHZ_CUSTOM_POLICIES.format(url=self.baseurl, client_id=client_id, realm=realm)
delete_url = "%s/%s" % (url, policy_id)
try:
return open_url(delete_url, method='DELETE', http_agent=self.http_agent, headers=self.restheaders, timeout=self.connection_timeout,
validate_certs=self.validate_certs)
except Exception as e:
self.module.fail_json(msg='Could not delete custom policy %s for client %s in realm %s: %s' % (id, client_id, realm, str(e)))
def get_authz_permission_by_name(self, name, client_id, realm):
"""Get authorization permission by name"""
url = URL_AUTHZ_POLICIES.format(url=self.baseurl, client_id=client_id, realm=realm)

211
plugins/modules/keycloak_authz_custom_policy.py Normal file
View file

@ -0,0 +1,211 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# Copyright (c) 2017, Eike Frost <ei@kefro.st>
# Copyright (c) 2021, Christophe Gilles <christophe.gilles54@gmail.com>
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or
# https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
module: keycloak_authz_custom_policy
short_description: Allows administration of Keycloak client custom Javascript policies via Keycloak API
version_added: 7.5.0
description:
- This module allows the administration of Keycloak client custom Javascript via the Keycloak REST
API. Custom Javascript policies are only available if a client has Authorization enabled and if
they have been deployed to the Keycloak server as JAR files.
- This module requires access to the REST API via OpenID Connect; the user connecting and the realm
being used must have the requisite access rights. In a default Keycloak installation, admin-cli
and an admin user would work, as would a separate realm definition with the scope tailored
to your needs and a user having the expected roles.
- The names of module options are snake_cased versions of the camelCase options used by Keycloak.
The Authorization Services paths and payloads have not officially been documented by the Keycloak project.
U(https://www.puppeteers.net/blog/keycloak-authorization-services-rest-api-paths-and-payload/)
attributes:
check_mode:
support: full
diff_mode:
support: none
options:
state:
description:
- State of the custom policy.
- On V(present), the custom policy will be created (or updated if it exists already).
- On V(absent), the custom policy will be removed if it exists.
choices: ['present', 'absent']
default: 'present'
type: str
name:
description:
- Name of the custom policy to create.
type: str
required: true
policy_type:
description:
- The type of the policy. This must match the name of the custom policy deployed to the server.
- Multiple policies pointing to the same policy type can be created, but their names have to differ.
type: str
required: true
client_id:
description:
- The V(clientId) of the Keycloak client that should have the custom policy attached to it.
- This is usually a human-readable name of the Keycloak client.
type: str
required: true
realm:
description:
- The name of the Keycloak realm the Keycloak client is in.
type: str
required: true
extends_documentation_fragment:
- community.general.keycloak
- community.general.attributes
author:
- Samuli Seppänen (@mattock)
'''
EXAMPLES = '''
- name: Manage Keycloak custom authorization policy
community.general.keycloak_authz_custom_policy:
name: OnlyOwner
state: present
policy_type: script-policy.js
client_id: myclient
realm: myrealm
auth_keycloak_url: http://localhost:8080/auth
auth_username: keycloak
auth_password: keycloak
auth_realm: master
'''
RETURN = '''
msg:
description: Message as to what action was taken.
returned: always
type: str
end_state:
description: Representation of the custom policy after module execution.
returned: on success
type: dict
contains:
name:
description: Name of the custom policy.
type: str
returned: when I(state=present)
sample: file:delete
policy_type:
description: Type of custom policy.
type: str
returned: when I(state=present)
sample: File delete
'''
from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI, \
keycloak_argument_spec, get_token, KeycloakError
from ansible.module_utils.basic import AnsibleModule
def main():
"""
Module execution
:return:
"""
argument_spec = keycloak_argument_spec()
meta_args = dict(
state=dict(type='str', default='present',
choices=['present', 'absent']),
name=dict(type='str', required=True),
policy_type=dict(type='str', required=True),
client_id=dict(type='str', required=True),
realm=dict(type='str', required=True)
)
argument_spec.update(meta_args)
module = AnsibleModule(argument_spec=argument_spec,
supports_check_mode=True,
required_one_of=(
[['token', 'auth_realm', 'auth_username', 'auth_password']]),
required_together=([['auth_realm', 'auth_username', 'auth_password']]))
result = dict(changed=False, msg='', end_state={})
# Obtain access token, initialize API
try:
connection_header = get_token(module.params)
except KeycloakError as e:
module.fail_json(msg=str(e))
kc = KeycloakAPI(module, connection_header)
# Convenience variables
state = module.params.get('state')
name = module.params.get('name')
policy_type = module.params.get('policy_type')
client_id = module.params.get('client_id')
realm = module.params.get('realm')
cid = kc.get_client_id(client_id, realm=realm)
if not cid:
module.fail_json(msg='Invalid client %s for realm %s' %
(client_id, realm))
before_authz_custom_policy = kc.get_authz_policy_by_name(
name=name, client_id=cid, realm=realm)
desired_authz_custom_policy = {}
desired_authz_custom_policy['name'] = name
desired_authz_custom_policy['type'] = policy_type
# Modifying existing custom policies is not possible
if before_authz_custom_policy and state == 'present':
result['msg'] = "Custom policy %s already exists" % (name)
result['changed'] = False
result['end_state'] = desired_authz_custom_policy
elif not before_authz_custom_policy and state == 'present':
if module.check_mode:
result['msg'] = "Would create custom policy %s" % (name)
else:
kc.create_authz_custom_policy(
payload=desired_authz_custom_policy, policy_type=policy_type, client_id=cid, realm=realm)
result['msg'] = "Custom policy %s created" % (name)
result['changed'] = True
result['end_state'] = desired_authz_custom_policy
elif before_authz_custom_policy and state == 'absent':
if module.check_mode:
result['msg'] = "Would remove custom policy %s" % (name)
else:
kc.remove_authz_custom_policy(
policy_id=before_authz_custom_policy['id'], client_id=cid, realm=realm)
result['msg'] = "Custom policy %s removed" % (name)
result['changed'] = True
result['end_state'] = {}
elif not before_authz_custom_policy and state == 'absent':
result['msg'] = "Custom policy %s does not exist" % (name)
result['changed'] = False
result['end_state'] = {}
module.exit_json(**result)
if __name__ == '__main__':
main()

5
tests/integration/targets/keycloak_authz_custom_policy/aliases Normal file
View file

@ -0,0 +1,5 @@
# Copyright (c) Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
unsupported

4
tests/integration/targets/keycloak_authz_custom_policy/policy/Containerfile Normal file
View file

@ -0,0 +1,4 @@
FROM quay.io/keycloak/keycloak:20.0.2
COPY policy.jar /opt/keycloak/providers/
RUN /opt/keycloak/bin/kc.sh build

3
tests/integration/targets/keycloak_authz_custom_policy/policy/Containerfile.license Normal file
View file

@ -0,0 +1,3 @@
Copyright (c) Ansible Project
GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
SPDX-License-Identifier: GPL-3.0-or-later

14
tests/integration/targets/keycloak_authz_custom_policy/policy/META-INF/keycloak-scripts.json Normal file
View file

@ -0,0 +1,14 @@
{
"policies": [
{
"name": "MyPolicy1",
"fileName": "policy-1.js",
"description": "My Policy 1"
},
{
"name": "MyPolicy2",
"fileName": "policy-2.js",
"description": "My Policy 2"
}
]
}

3
tests/integration/targets/keycloak_authz_custom_policy/policy/META-INF/keycloak-scripts.json.license Normal file
View file

@ -0,0 +1,3 @@
Copyright (c) Ansible Project
GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
SPDX-License-Identifier: GPL-3.0-or-later

2
tests/integration/targets/keycloak_authz_custom_policy/policy/build-policy.sh Executable file
View file

@ -0,0 +1,2 @@
#!/bin/sh
zip -r policy.jar META-INF/keycloak-scripts.json policy-1.js policy-2.js

3
tests/integration/targets/keycloak_authz_custom_policy/policy/build-policy.sh.license Normal file
View file

@ -0,0 +1,3 @@
Copyright (c) Ansible Project
GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
SPDX-License-Identifier: GPL-3.0-or-later

1
tests/integration/targets/keycloak_authz_custom_policy/policy/policy-1.js Normal file
View file

@ -0,0 +1 @@
$evaluation.grant();

3
tests/integration/targets/keycloak_authz_custom_policy/policy/policy-1.js.license Normal file
View file

@ -0,0 +1,3 @@
Copyright (c) Ansible Project
GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
SPDX-License-Identifier: GPL-3.0-or-later

1
tests/integration/targets/keycloak_authz_custom_policy/policy/policy-2.js Normal file
View file

@ -0,0 +1 @@
$evaluation.grant();

3
tests/integration/targets/keycloak_authz_custom_policy/policy/policy-2.js.license Normal file
View file

@ -0,0 +1,3 @@
Copyright (c) Ansible Project
GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
SPDX-License-Identifier: GPL-3.0-or-later

27
tests/integration/targets/keycloak_authz_custom_policy/readme.adoc Normal file
View file

@ -0,0 +1,27 @@
// Copyright (c) Ansible Project
// GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
// SPDX-License-Identifier: GPL-3.0-or-later
To be able to run these integration tests a keycloak server must be
reachable under a specific url with a specific admin user and password.
The exact values expected for these parameters can be found in
'vars/main.yml' file. A vanilla Keycloak server will not be sufficient:
you will need to deploy a custom JAR file with two policies:
* _MyPolicy1:_ policy-1.js
* _MyPolicy2:_ policy-2.js
To create a customized Keycloak test instance running on Podman first
install the "zip" command, go to the policy subdirectory and then do
[source,shell]
----
./build-policy.sh
podman build --tag keycloak_authz_custom_policy_test:1.0.0 .
podman rm mykeycloak && podman run --name mykeycloak -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=password -e KC_HTTP_RELATIVE_PATH=/auth localhost/keycloak_authz_custom_policy_test:1.0.0 start-dev
----
This process probably also work with Docker just by replacing _podman_ with
_docker_. Modify the FROM argument in Containerfile to change Keycloak version
to test against. Quarkus versions of Keycloak should work - older versions
will not.

168
tests/integration/targets/keycloak_authz_custom_policy/tasks/main.yml Normal file
View file

@ -0,0 +1,168 @@
---
# Copyright (c) Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
- name: Remove keycloak client to avoid failures from previous failed runs
community.general.keycloak_client:
auth_keycloak_url: "{{ url }}"
auth_realm: "{{ admin_realm }}"
auth_username: "{{ admin_user }}"
auth_password: "{{ admin_password }}"
realm: "{{ realm }}"
client_id: "{{ client_id }}"
state: absent
- name: Create keycloak client with authorization services enabled
community.general.keycloak_client:
auth_keycloak_url: "{{ url }}"
auth_realm: "{{ admin_realm }}"
auth_username: "{{ admin_user }}"
auth_password: "{{ admin_password }}"
realm: "{{ realm }}"
client_id: "{{ client_id }}"
state: present
enabled: true
public_client: false
service_accounts_enabled: true
authorization_services_enabled: true
- name: Create first custom policy (check_mode)
community.general.keycloak_authz_custom_policy:
auth_keycloak_url: "{{ url }}"
auth_realm: "{{ admin_realm }}"
auth_username: "{{ admin_user }}"
auth_password: "{{ admin_password }}"
name: FirstCustomPolicy
state: present
policy_type: script-policy-1.js
realm: "{{ realm }}"
client_id: "{{ client_id }}"
check_mode: true
register: result
- name: Assert that first custom policy was not created
assert:
that:
- result is changed
- result.end_state != {}
- result.end_state.name == "FirstCustomPolicy"
- result.end_state.type == "script-policy-1.js"
- result.msg == 'Would create custom policy FirstCustomPolicy'
- name: Create first custom policy
community.general.keycloak_authz_custom_policy:
auth_keycloak_url: "{{ url }}"
auth_realm: "{{ admin_realm }}"
auth_username: "{{ admin_user }}"
auth_password: "{{ admin_password }}"
name: FirstCustomPolicy
state: present
policy_type: script-policy-1.js
realm: "{{ realm }}"
client_id: "{{ client_id }}"
register: result
- name: Assert that first custom policy was created
assert:
that:
- result is changed
- result.end_state != {}
- result.end_state.name == "FirstCustomPolicy"
- result.end_state.type == "script-policy-1.js"
- result.msg == 'Custom policy FirstCustomPolicy created'
- name: Attempt to update first custom policy (not possible)
community.general.keycloak_authz_custom_policy:
auth_keycloak_url: "{{ url }}"
auth_realm: "{{ admin_realm }}"
auth_username: "{{ admin_user }}"
auth_password: "{{ admin_password }}"
name: FirstCustomPolicy
state: present
policy_type: script-policy-2.js
realm: "{{ realm }}"
client_id: "{{ client_id }}"
register: result
- name: Assert that first custom policy was not modified
assert:
that:
- result is not changed
- result.end_state != {}
- result.end_state.name == "FirstCustomPolicy"
- result.end_state.type == "script-policy-2.js"
- result.msg == 'Custom policy FirstCustomPolicy already exists'
# Ensure that we can create multiple instances of the custom policy
- name: Create second instance of the custom policy
community.general.keycloak_authz_custom_policy:
auth_keycloak_url: "{{ url }}"
auth_realm: "{{ admin_realm }}"
auth_username: "{{ admin_user }}"
auth_password: "{{ admin_password }}"
name: SecondCustomPolicy
state: present
policy_type: script-policy-1.js
realm: "{{ realm }}"
client_id: "{{ client_id }}"
register: result
- name: Assert that second instance of the custom policy was created
assert:
that:
- result is changed
- result.end_state != {}
- result.end_state.name == "SecondCustomPolicy"
- result.end_state.type == "script-policy-1.js"
- result.msg == 'Custom policy SecondCustomPolicy created'
- name: Remove second instance of the custom policy (check_mode)
community.general.keycloak_authz_custom_policy:
auth_keycloak_url: "{{ url }}"
auth_realm: "{{ admin_realm }}"
auth_username: "{{ admin_user }}"
auth_password: "{{ admin_password }}"
name: SecondCustomPolicy
state: absent
policy_type: script-policy-1.js
realm: "{{ realm }}"
client_id: "{{ client_id }}"
check_mode: true
register: result
- name: Assert that second custom policy was not removed
assert:
that:
- result is changed
- result.end_state == {}
- result.msg == 'Would remove custom policy SecondCustomPolicy'
- name: Remove second instance of the custom policy
community.general.keycloak_authz_custom_policy:
auth_keycloak_url: "{{ url }}"
auth_realm: "{{ admin_realm }}"
auth_username: "{{ admin_user }}"
auth_password: "{{ admin_password }}"
name: SecondCustomPolicy
state: absent
policy_type: script-policy-1.js
realm: "{{ realm }}"
client_id: "{{ client_id }}"
register: result
- name: Assert that second custom policy was removed
assert:
that:
- result is changed
- result.end_state == {}
- result.msg == 'Custom policy SecondCustomPolicy removed'
- name: Remove keycloak client
community.general.keycloak_client:
auth_keycloak_url: "{{ url }}"
auth_realm: "{{ admin_realm }}"
auth_username: "{{ admin_user }}"
auth_password: "{{ admin_password }}"
realm: "{{ realm }}"
client_id: "{{ client_id }}"
state: absent

11
tests/integration/targets/keycloak_authz_custom_policy/vars/main.yml Normal file
View file

@ -0,0 +1,11 @@
---
# Copyright (c) Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
url: http://localhost:8080/auth
admin_realm: master
admin_user: admin
admin_password: password
realm: master
client_id: authz