community.general/plugins/modules/gitlab_group_access_token.py

#!/usr/bin/python
# -*- coding: utf-8 -*-

# Copyright (c) 2024, Zoran Krleza (zoran.krleza@true-north.hr)
# Based on code:
# Copyright (c) 2019, Guillaume Martinez (lunik@tiwabbit.fr)
# Copyright (c) 2018, Marcus Watkins <marwatk@marcuswatkins.net>
# Copyright (c) 2013, Phillip Gentry <phillip@cx.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 = r'''
module: gitlab_group_access_token
short_description: Manages GitLab group access tokens
version_added: 8.4.0
description:
  - Creates and revokes group access tokens.
author:
  - Zoran Krleza (@pixslx)
requirements:
  - python-gitlab >= 3.1.0
extends_documentation_fragment:
  - community.general.auth_basic
  - community.general.gitlab
  - community.general.attributes
notes:
  - Access tokens can not be changed. If a parameter needs to be changed, an acceess token has to be recreated.
    Whether tokens will be recreated is controlled by the O(recreate) option, which defaults to V(never).
  - Token string is contained in the result only when access token is created or recreated. It can not be fetched afterwards.
  - Token matching is done by comparing O(name) option.

attributes:
  check_mode:
    support: full
  diff_mode:
    support: none

options:
  group:
    description:
      - ID or full path of group in the form of group/subgroup.
    required: true
    type: str
  name:
    description:
      - Access token's name.
    required: true
    type: str
  scopes:
    description:
      - Scope of the access token.
    required: true
    type: list
    elements: str
    aliases: ["scope"]
    choices: ["api", "read_api", "read_registry", "write_registry", "read_repository", "write_repository", "create_runner", "ai_features", "k8s_proxy"]
  access_level:
    description:
      - Access level of the access token.
    type: str
    default: maintainer
    choices: ["guest", "reporter", "developer", "maintainer", "owner"]
  expires_at:
    description:
      - Expiration date of the access token in C(YYYY-MM-DD) format.
      - Make sure to quote this value in YAML to ensure it is kept as a string and not interpreted as a YAML date.
    type: str
    required: true
  recreate:
    description:
      - Whether the access token will be recreated if it already exists.
      - When V(never) the token will never be recreated.
      - When V(always) the token will always be recreated.
      - When V(state_change) the token will be recreated if there is a difference between desired state and actual state.
    type: str
    choices: ["never", "always", "state_change"]
    default: never
  state:
    description:
      - When V(present) the access token will be added to the group if it does not exist.
      - When V(absent) it will be removed from the group if it exists.
    default: present
    type: str
    choices: [ "present", "absent" ]
'''

EXAMPLES = r'''
- name: "Creating a group access token"
  community.general.gitlab_group_access_token:
    api_url: https://gitlab.example.com/
    api_token: "somegitlabapitoken"
    group: "my_group/my_subgroup"
    name: "group_token"
    expires_at: "2024-12-31"
    access_level: developer
    scopes:
      - api
      - read_api
      - read_repository
      - write_repository
    state: present

- name: "Revoking a group access token"
  community.general.gitlab_group_access_token:
    api_url: https://gitlab.example.com/
    api_token: "somegitlabapitoken"
    group: "my_group/my_group"
    name: "group_token"
    expires_at: "2024-12-31"
    scopes:
      - api
      - read_api
      - read_repository
      - write_repository
    state: absent

- name: "Change (recreate) existing token if its actual state is different than desired state"
  community.general.gitlab_group_access_token:
    api_url: https://gitlab.example.com/
    api_token: "somegitlabapitoken"
    group: "my_group/my_group"
    name: "group_token"
    expires_at: "2024-12-31"
    scopes:
      - api
      - read_api
      - read_repository
      - write_repository
    recreate: state_change
    state: present
'''

RETURN = r'''
access_token:
  description:
    - API object.
    - Only contains the value of the token if the token was created or recreated.
  returned: success and O(state=present)
  type: dict
'''

from datetime import datetime

from ansible.module_utils.api import basic_auth_argument_spec
from ansible.module_utils.basic import AnsibleModule
from ansible.module_utils.common.text.converters import to_native

from ansible_collections.community.general.plugins.module_utils.gitlab import (
    auth_argument_spec, find_group, gitlab_authentication, gitlab
)

ACCESS_LEVELS = dict(guest=10, reporter=20, developer=30, maintainer=40, owner=50)


class GitLabGroupAccessToken(object):
    def __init__(self, module, gitlab_instance):
        self._module = module
        self._gitlab = gitlab_instance
        self.access_token_object = None

    '''
    @param project Project Object
    @param group Group Object
    @param arguments Attributes of the access_token
    '''
    def create_access_token(self, group, arguments):
        changed = False
        if self._module.check_mode:
            return True

        try:
            self.access_token_object = group.access_tokens.create(arguments)
            changed = True
        except (gitlab.exceptions.GitlabCreateError) as e:
            self._module.fail_json(msg="Failed to create access token: %s " % to_native(e))

        return changed

    '''
    @param project Project object
    @param group Group Object
    @param name of the access token
    '''
    def find_access_token(self, group, name):
        access_tokens = group.access_tokens.list(all=True)
        for access_token in access_tokens:
            if (access_token.name == name):
                self.access_token_object = access_token
                return False
        return False

    def revoke_access_token(self):
        if self._module.check_mode:
            return True

        changed = False
        try:
            self.access_token_object.delete()
            changed = True
        except (gitlab.exceptions.GitlabCreateError) as e:
            self._module.fail_json(msg="Failed to revoke access token: %s " % to_native(e))

        return changed

    def access_tokens_equal(self):
        if self.access_token_object.name != self._module.params['name']:
            return False
        if self.access_token_object.scopes != self._module.params['scopes']:
            return False
        if self.access_token_object.access_level != ACCESS_LEVELS[self._module.params['access_level']]:
            return False
        if self.access_token_object.expires_at != self._module.params['expires_at']:
            return False
        return True


def main():
    argument_spec = basic_auth_argument_spec()
    argument_spec.update(auth_argument_spec())
    argument_spec.update(dict(
        state=dict(type='str', default="present", choices=["absent", "present"]),
        group=dict(type='str', required=True),
        name=dict(type='str', required=True),
        scopes=dict(type='list',
                    required=True,
                    aliases=['scope'],
                    elements='str',
                    choices=['api',
                             'read_api',
                             'read_registry',
                             'write_registry',
                             'read_repository',
                             'write_repository',
                             'create_runner',
                             'ai_features',
                             'k8s_proxy']),
        access_level=dict(type='str', required=False, default='maintainer', choices=['guest', 'reporter', 'developer', 'maintainer', 'owner']),
        expires_at=dict(type='str', required=True),
        recreate=dict(type='str', default='never', choices=['never', 'always', 'state_change'])
    ))

    module = AnsibleModule(
        argument_spec=argument_spec,
        mutually_exclusive=[
            ['api_username', 'api_token'],
            ['api_username', 'api_oauth_token'],
            ['api_username', 'api_job_token'],
            ['api_token', 'api_oauth_token'],
            ['api_token', 'api_job_token']
        ],
        required_together=[
            ['api_username', 'api_password']
        ],
        required_one_of=[
            ['api_username', 'api_token', 'api_oauth_token', 'api_job_token']
        ],
        supports_check_mode=True
    )

    state = module.params['state']
    group_identifier = module.params['group']
    name = module.params['name']
    scopes = module.params['scopes']
    access_level_str = module.params['access_level']
    expires_at = module.params['expires_at']
    recreate = module.params['recreate']

    access_level = ACCESS_LEVELS[access_level_str]

    try:
        datetime.strptime(expires_at, '%Y-%m-%d')
    except ValueError:
        module.fail_json(msg="Argument expires_at is not in required format YYYY-MM-DD")

    gitlab_instance = gitlab_authentication(module)

    gitlab_access_token = GitLabGroupAccessToken(module, gitlab_instance)

    group = find_group(gitlab_instance, group_identifier)
    if group is None:
        module.fail_json(msg="Failed to create access token: group %s does not exists" % group_identifier)

    gitlab_access_token_exists = False
    gitlab_access_token.find_access_token(group, name)
    if gitlab_access_token.access_token_object is not None:
        gitlab_access_token_exists = True

    if state == 'absent':
        if gitlab_access_token_exists:
            gitlab_access_token.revoke_access_token()
            module.exit_json(changed=True, msg="Successfully deleted access token %s" % name)
        else:
            module.exit_json(changed=False, msg="Access token does not exists")

    if state == 'present':
        if gitlab_access_token_exists:
            if gitlab_access_token.access_tokens_equal():
                if recreate == 'always':
                    gitlab_access_token.revoke_access_token()
                    gitlab_access_token.create_access_token(group, {'name': name, 'scopes': scopes, 'access_level': access_level, 'expires_at': expires_at})
                    module.exit_json(changed=True, msg="Successfully recreated access token", access_token=gitlab_access_token.access_token_object._attrs)
                else:
                    module.exit_json(changed=False, msg="Access token already exists", access_token=gitlab_access_token.access_token_object._attrs)
            else:
                if recreate == 'never':
                    module.fail_json(msg="Access token already exists and its state is different. It can not be updated without recreating.")
                else:
                    gitlab_access_token.revoke_access_token()
                    gitlab_access_token.create_access_token(group, {'name': name, 'scopes': scopes, 'access_level': access_level, 'expires_at': expires_at})
                    module.exit_json(changed=True, msg="Successfully recreated access token", access_token=gitlab_access_token.access_token_object._attrs)
        else:
            gitlab_access_token.create_access_token(group, {'name': name, 'scopes': scopes, 'access_level': access_level, 'expires_at': expires_at})
            if module.check_mode:
                module.exit_json(changed=True, msg="Successfully created access token", access_token={})
            else:
                module.exit_json(changed=True, msg="Successfully created access token", access_token=gitlab_access_token.access_token_object._attrs)


if __name__ == '__main__':
    main()