Welcome to oktalib’s documentation!¶

Contents:

oktalib¶

A python library for interfacing with OKTA’s api

Documentation: https://oktalib.readthedocs.org/en/latest

Development Workflow¶

The workflow supports the following steps

lint

test

build

document

upload

graph

These actions are supported out of the box by the corresponding scripts under _CI/scripts directory with sane defaults based on best practices. Sourcing setup_aliases.ps1 for windows powershell or setup_aliases.sh in bash on Mac or Linux will provide with handy aliases for the shell of all those commands prepended with an underscore.

The bootstrap script creates a .venv directory inside the project directory hosting the virtual environment. It uses pipenv for that. It is called by all other scripts before they do anything. So one could simple start by calling _lint and that would set up everything before it tried to actually lint the project

Once the code is ready to be delivered the _tag script should be called accepting one of three arguments, patch, minor, major following the semantic versioning scheme. So for the initial delivery one would call

$ _tag –minor

which would bump the version of the project to 0.1.0 tag it in git and do a push and also ask for the change and automagically update HISTORY.rst with the version and the change provided.

So the full workflow after git is initialized is:

repeat as necessary (of course it could be test - code - lint :) ) * code * lint * test

commit and push

develop more through the code-lint-test cycle

tag (with the appropriate argument)

build

upload (if you want to host your package in pypi)

document (of course this could be run at any point)

Important Information¶

This template is based on pipenv. In order to be compatible with requirements.txt so the actual created package can be used by any part of the existing python ecosystem some hacks were needed. So when building a package out of this do not simple call

$ python setup.py sdist bdist_egg

as this will produce an unusable artifact with files missing. Instead use the provided build and upload scripts that create all the necessary files in the artifact.

Project Features¶

Manages groups, users and applications

Todo¶

This code is MVP. It requires a lot of optimizations and extensions.
Things to do are, try to make the retrieving faster and implement smart caching for entities.

Installation¶

At the command line:

$ pip install oktalib

Or, if you have virtualenvwrapper installed:

$ mkvirtualenv oktalib
$ pip install oktalib

Or, if you are using pipenv:

$ pipenv install oktalib

Usage¶

To develop on oktalib:

# The following commands require pipenv as a dependency

# To lint the project
_CI/scripts/lint.py

# To execute the testing
_CI/scripts/test.py

# To create a graph of the package and dependency tree
_CI/scripts/graph.py

# To build a package of the project under the directory "dist/"
_CI/scripts/build.py

# To see the package version
_CI/scipts/tag.py

# To bump semantic versioning [--major|--minor|--patch]
_CI/scipts/tag.py --major|--minor|--patch

# To upload the project to a pypi repo if user and password are properly provided
_CI/scripts/upload.py

# To build the documentation of the project
_CI/scripts/document.py

To use oktalib in a project:

from oktalib import Okta
okta = Okta(url, token)


# Working with groups

# enumerate groups in okta
for group in okta.groups:
    print group.name

# create a group
group = okta.create_group(GROUP_NAME, GROUP_DESCRIPTION)

# or get an existing one
group = okta.get_group_by_name(GROUP_NAME)

# delete a group
okta.delete_group(GROUP_NAME)

# or
group = okta.get_group_by_name(GROUP_NAME)
group.delete()

# add a user to a group
group.add_user_by_login(USERNAME)


# Working with users

# enumerate users in okta
for user in okta.users:
    print user.login

# create a user
user = okta.create_user(FIRST_NAME,
                        LAST_NAME,
                        EMAIL,
                        OKTA_USERNAME)

# or get an existing one
user = okta.get_user_by_login(USER_LOGIN)

# delete a user
okta.delete_user(USER_NAME)

# get groups of reference user
user = okta.get_user_by_login(USER_LOGIN)
groups = user.get_member_groups()
# or
user = okta.get_user_by_login(USER_LOGIN)
user.delete()

Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Submit Feedback¶

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.

Get Started!¶

Ready to contribute? Here’s how to set up oktalib for local development.

Clone your fork locally:

$ git clone https://github.com/schubergphilis/oktalib.git

Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your clone for local development:
```
$ mkvirtualenv oktalib
$ cd oktalib/
$ python setup.py develop
```
Create a branch for local development:
```
$ git checkout -b name-of-your-bugfix-or-feature
```
Now you can make your changes locally.

Commit your changes and push your branch to the server:

$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

Submit a merge request

oktalib¶

oktalib package¶

Subpackages¶

oktalib.entities package¶

Submodules¶

oktalib.entities.core module¶

Main code for core.

class oktalib.entities.core.Entity(okta_instance, data)[source]¶

Bases: object

The core object of okta.

created_at¶

The date and time of the group’s creation.

Returns:	The datetime object of when the group was created
Return type:	datetime

id¶

The id of the entity.

Returns:	The internal id of the entity
Return type:	basestring

last_updated_at¶

The date and time of the entity’s last update.

Returns:	The datetime object of when the entity was last updated
Return type:	datetime

url¶

The url of the entity.

Returns:	None in the core entity.

All objects inheriting from this would either expose this from their data or construct and overwrite this.

oktalib.entities.entities module¶

Main code for entities.

class oktalib.entities.entities.Application(okta_instance, data)[source]¶

Bases: oktalib.entities.core.Entity

Models the apps in okta.

accessibility¶

The accessibility of the application.

Returns:	The accessibility of the application
Return type:	dictionary

activate()[source]¶

Activates the application.

Returns:	True on success, False otherwise
Return type:	bool

add_group_by_id(group_id)[source]¶

Adds a group to the application.

Parameters:	group_id – The id of the group to add
Returns:	True on success, False otherwise

add_group_by_name(group_name)[source]¶

Adds a group to the application.

Parameters:	group_name – The name of the group to add
Returns:	True on success, False otherwise

assign_group_to_saml_user_roles(group_id, role, saml_roles)[source]¶

Assigns an okta group to an okta application with saml user roles.

Parameters:	group_id – The id of the group to be associated role – The aws role that okta uses to assume SAML roles in other accounts saml_roles – the SAML Roles to be assumed
Returns:	The status of the assignment( True or False )
Return type:	Bool

credentials¶

The credentials of the application.

Returns:	The credentials of the application
Return type:	dictionary

deactivate()[source]¶

Deactivates the application.

Returns:	True on success, False otherwise
Return type:	bool

features¶

The features of the application.

Returns:	The features of the application
Return type:	dictionary

get_associated_saml_roles()[source]¶

Returns the Saml IAM Roles associated with the application.

Returns:	List of saml iam roles
Return type:	list

get_group_assignment_by_group_name(name)[source]¶

Retrieves a group assignment by a group name.

Parameters:	name – The name of the group assignment to retrieve.
Returns:	The matching group assignment if found else None.
Return type:	group_assignment (GroupAssignment)

get_user_assignment_by_email(email)[source]¶

Retrieves a user assignment by a user email.

Parameters:	email – The email of the user assignment to retrieve.
Returns:	The matching user assignment if found else None.
Return type:	user_assignment (UserAssignment)

group_assignments¶

The group assignments to the application.

Returns:	A generator of group assignments for application
Return type:	generator

groups¶

The groups of the application.

Returns:	A generator of Group objects for the groups of the application
Return type:	generator

label¶

The label of the application.

Returns:	The label of the application
Return type:	basestring

name¶

The name of the application.

Returns:	The name of the application
Return type:	basestring

notification_settings¶

The notification settings of the application.

Returns:	The notification settings of the application
Return type:	dictionary

remove_group_by_id(group_id)[source]¶

Removes a group from the application.

Parameters:	group_id – The id of the group to remove
Returns:	True on success, False otherwise

remove_group_by_name(group_name)[source]¶

Removes a group from the application.

Parameters:	group_name – The name of the group to remove
Returns:	True on success, False otherwise

settings¶

The settings of the application.

Returns:	The settings of the application
Return type:	dictionary

sign_on_mode¶

The sign on mode of the application.

Returns:	The sign on mode of the application
Return type:	basestring

sign_on_settings¶

The sign on settings of the application.

Returns:	The sign on settings of the application
Return type:	dictionary

status¶

The status of the application.

Returns:	The status of the application
Return type:	basestring

url¶

The url of the application.

Returns:	The url of the application
Return type:	string

user_assignments¶

The user assignments to the application.

Returns:	A generator of user assignments for application
Return type:	generator

users¶

The users of the application.

Returns:	A generator of User objects for the users of the application
Return type:	generator

visibility¶

The visibility of the application.

Returns:	The visibility of the application
Return type:	dictionary

class oktalib.entities.entities.Group(okta_instance, data)[source]¶

Bases: oktalib.entities.core.Entity

Models the group object of okta.

add_to_application_with_label(application_label)[source]¶

Adds the group to an application.

Parameters:	application_label – The label of the application to add the group to
Returns:	True on success, False otherwise

add_user_by_id(id_)[source]¶

Adds a user to the group.

Parameters:	id – The id of the user to add
Returns:	True on success, False otherwise

add_user_by_login(login)[source]¶

Adds a user to the group.

Parameters:	login – The login of the user to add
Returns:	True on success, False otherwise

applications¶

The applications of the group.

Returns:	A generator of Application objects for the applications of the group
Return type:	generator

delete()[source]¶

Deletes the group from okta.

Returns:	True on success, False otherwise
Return type:	bool

description¶

The description of the group.

Returns:	The description of the group
Return type:	string

last_membership_updated_at¶

The date and time of the group’s last membership update.

Returns:	The datetime object of when the group’s memberships were last updated
Return type:	datetime

name¶

The name of the group.

Returns:	The name of the group
Return type:	string

object_classes¶

The classes of the group.

Returns:	The tuple of the classes of the group
Return type:	tuple

profile¶

The profile of the group.

Returns:	The profile of the group
Return type:	dict

remove_from_application_with_label(application_label)[source]¶

Removes the group from an application.

Parameters:	application_label – The label of the application to remove the group from
Returns:	True on success, False otherwise

remove_user_by_id(id_)[source]¶

Remove a user from the group.

Parameters:	id – The id of the user to remove
Returns:	True on success, False otherwise

remove_user_by_login(login)[source]¶

Removes a user from the group.

Parameters:	login – The login of the user to remove
Returns:	True on success, False otherwise

type¶

The type of the group.

Returns:	The name of the type of the group
Return type:	string

url¶

The url of the group.

Returns:	The url of the group
Return type:	string

users¶

The users of the group.

Returns:	A generator of User objects for the users of the group
Return type:	generator

class oktalib.entities.entities.GroupAssignment(okta_instance, data)[source]¶

Bases: oktalib.entities.entities.Group

Models the group assignment object of okta for apps.

priority¶

The priority of the group assignment.

Returns:	The priority of the group.
Return type:	int

profile_role¶: Profile role.

profile_saml_roles¶: Profile saml roles.

class oktalib.entities.entities.User(okta_instance, data)[source]¶

Bases: oktalib.entities.core.Entity

Models the user object of okta.

activate()[source]¶

Activate the user.

Returns:	True on success, False otherwise

activated_at¶

The date and time of the users’s activation.

Returns:	The datetime object of when the user was activated
Return type:	datetime

city¶

The city of the user.

Returns:	The city of the user
Return type:	string

contry_code¶

The contry code of the user.

Returns:	The country code of the user
Return type:	string

credentials¶

The credentials of the user.

Returns:	The credentials of the user
Return type:	dictionary

deactivate()[source]¶

Deactivate the user.

Returns:	True on success, False otherwise

delete()[source]¶

Deletes the user from okta.

Returns:	True on success, False otherwise
Return type:	bool

department¶

The department of the user.

Returns:	The department of the user
Return type:	string

display_name¶

The display name of the user.

Returns:	The display name of the user
Return type:	string

email¶

The email of the user.

Returns:	The email of the user
Return type:	string

employee_number¶

The employee number of the user.

Returns:	The employee number of the user
Return type:	string

expire_password()[source]¶

Expires the user’s password.

Returns:	True on success, False otherwise

first_name¶

The first name of the user.

Returns:	The first name of the user
Return type:	string

groups¶

Lists the groups the user is a member of.

Returns:	A generator of Group objects for which the user is member of
Return type:	generator

last_login_at¶

The date and time of the users’s last login.

Returns:	The datetime object of when the user last logged in
Return type:	datetime

last_name¶

The last name of the user.

Returns:	The last name of the user
Return type:	string

locale¶

The locale of the user.

Returns:	The locale of the user
Return type:	string

login¶

The login of the user.

Returns:	The login of the user
Return type:	string

manager¶

The manager of the user.

Returns:	The manager of the user
Return type:	string

mobile_phone¶

The mobile phone of the user.

Returns:	The mobile phone of the user
Return type:	string

organization¶

The organization of the user.

Returns:	The organization of the user
Return type:	string

password_changed_at¶

The date and time of the users’s last password change.

Returns:	The datetime object of when the user last changed password
Return type:	datetime

primary_phone¶

The primary phone of the user.

Returns:	The primary phone of the user
Return type:	string

reset_password()[source]¶

Resets the user’s password.

Returns:	True on success, False otherwise

second_email¶

The second email of the user.

Returns:	The second email of the user
Return type:	string

set_password(password)[source]¶

Set a password for the user.

Returns:	True on success, False otherwise

set_temporary_password()[source]¶

Sets a temporary password for the user.

Returns:	Password on success, None otherwise
Return type:	string

status¶

The status of the user.

Returns:	The status of the user
Return type:	string

status_changed_at¶

The date and time of the users’s status change.

Returns:	The datetime object of when the user had last changed status
Return type:	datetime

street_address¶

The street address of the user.

Returns:	The street address of the user
Return type:	string

suspend()[source]¶

Suspends the user.

Returns:	True on success, False otherwise

title¶

The title of the user.

Returns:	The title of the user
Return type:	string

unlock()[source]¶

Unlocks the user.

Returns:	True on success, False otherwise

unsuspend()[source]¶

Unsuspends the user.

Returns:	True on success, False otherwise

update_password(old_password, new_password)[source]¶

Changes the user’s password.

Returns:	True on success, False otherwise

update_profile(new_profile)[source]¶

Update a user’s profile in okta.

Parameters:	new_profile – A object with attributes to change (example: {‘profile’: {‘firstName’: ‘Test’}})
Returns:	True or False depending on success
Return type:	Bool

update_security_question(password, question, answer)[source]¶

Changes the user’s security question and answer.

Returns:	True on success, False otherwise

url¶

The url of the user.

Returns:	The url of the user
Return type:	string

zip_code¶

The zip code of the user.

Returns:	The zip code of the user
Return type:	string

class oktalib.entities.entities.UserAssignment(okta_instance, data)[source]¶

Bases: oktalib.entities.entities.User

Models the user assignment object of okta for apps.

email¶

The email of the user.

Returns:	The email of the user.
Return type:	email (str)

group¶

The group that the user assignment refers to.

Returns:	The group that the user assignment refers to.
Return type:	group (Group)

profile_role¶: Profile role.

profile_saml_roles¶: Profile saml roles.

Module contents¶

entities package.

Import all parts from entities here

Submodules¶

oktalib.oktalib module¶

Main code for oktalib.

class oktalib.oktalib.Okta(host, token)[source]¶

Bases: object

Models the api of okta.

applications¶

The applications configured in okta.

Returns:	The generator of applications configured in okta
Return type:	generator

assign_group_to_application(application_label, group_name)[source]¶

Assigns a group to an application.

Parameters:	application_label – The label of the application to assign the group to group_name – The group name to assign to the application
Returns:	True on success, False otherwise

create_group(name, description)[source]¶

Creates a group in okta.

Parameters:	name – The name of the group to create description – The description of the group to create
Returns:	The created group object on success, None otherwise

create_user(first_name, last_name, email, login, password=None, enabled=True)[source]¶

Creates a user in okta.

Parameters:	first_name – The first name of the user last_name – The last name of the user email – The email of the user login – The login of the user password – The password of the user enabled – A flag whether the user should be enabled or not Defaults to True
Returns:	The created user on success, None otherwise
Return type:	User

delete_group(name)[source]¶

Deletes a group from okta.

Parameters:	name – The name of the group to delete
Returns:	True on success, False otherwise
Return type:	bool
Raises:	`InvalidGroup` – The group provided as argument does not exist.

get_application_by_id(id_)[source]¶

Retrieves an application by id.

Parameters:	id – The id of the application to retrieve
Returns:	Application Object

get_application_by_label(label)[source]¶

Retrieves an application by label.

Parameters:	label – The label of the application to retrieve
Returns:	Application Object

get_group_by_id(group_id)[source]¶

Retrieves the group (of any type) by id.

Parameters:	group_id – The id of the group to retrieve
Returns:	The group if a match is found else None
Return type:	Group

get_group_by_name(name)[source]¶

Retrieves the first group (of any type) by name.

Parameters:	name – The name of the group to retrieve
Returns:	The group if a match is found else None
Return type:	Group

get_group_type_by_name(name, group_type='OKTA_GROUP')[source]¶

Retrieves the group type of okta by name.

Parameters:	group_type – The type of okta group to retrieve name – The name of the group to retrieve
Returns:	The group if a match is found else None
Return type:	Group

get_user_by_login(login)[source]¶

Retrieves a user by login.

Parameters:	login – The login to match the user with
Returns:	The user if found, None otherwise
Return type:	User

groups¶

The groups configured in okta.

Returns:	The generator of groups configured in okta
Return type:	generator

remove_group_from_application(application_label, group_name)[source]¶

Removes a group from an application.

Parameters:	application_label – The label of the application to remove the group from group_name – The name of the group to remove from the application
Returns:	True on success, False otherwise

search_groups_by_name(name)[source]¶

Retrieves the groups (of any type) by name.

Parameters:	name – The name of the groups to retrieve
Returns:	A list of groups if a match is found else an empty list
Return type:	list

search_users(value)[source]¶

Retrieves a list of users by looking into name, last name and email.

Parameters:	value – The value to match with
Returns:	The users if found, empty list otherwise
Return type:	list

search_users_by_email(email)[source]¶

Retrieves a list of users by email.

Parameters:	email – The email to match the user with
Returns:	The users if found, empty list otherwise
Return type:	list

users¶

The users configured in okta.

Returns:	The generator of users configured in okta
Return type:	generator

oktalib.oktalibexceptions module¶

Custom exception code for oktalib.

exception oktalib.oktalibexceptions.ApiLimitReached[source]¶

Bases: Exception

The api limits are close to being reached.

exception oktalib.oktalibexceptions.AuthFailed[source]¶

Bases: Exception

The authentication was not possible. Invalid token maybe.

exception oktalib.oktalibexceptions.InvalidApplication[source]¶

Bases: Exception

The application provided is invalid.

exception oktalib.oktalibexceptions.InvalidGroup[source]¶

Bases: Exception

The group provided is invalid.

exception oktalib.oktalibexceptions.InvalidUser[source]¶

Bases: Exception

The user provided is invalid.

exception oktalib.oktalibexceptions.ServerError[source]¶

Bases: Exception

A server has responded with an error code.

exception oktalib.oktalibexceptions.UnableToUpdate[source]¶

Bases: Exception

Could not update use property.

Module contents¶

oktalib package.

Import all parts from oktalib here

Credits¶

Development Lead¶

Costas Tyfoxylos <ctyfoxylos@schubergphilis.com>

Contributors¶

Yorick Hoorneman <yhoorneman@schubergphilis.com>

History¶

0.1.0 (25-05-2018)¶

First release

1.0.0 (19-10-2018)¶

Updated template to python3.7 Dropped support for python2.7

1.1.0 (23-10-2018)¶

Added setting of user password capability

1.1.1 (25-10-2018)¶

Updated template and dependencies

1.1.2 (17-12-2018)¶

Updated requests version.

1.1.3 (11-01-2019)¶

Updated requests module and fixed requirements generation.

1.1.4 (20-09-2019)¶

Update get_applicatio_by_id

1.1.5 (20-09-2019)¶

Added limit

1.1.6 (23-09-2019)¶

Fix applications method

1.1.7 (18-10-2019)¶

bumped dependencies

1.1.8 (18-10-2019)¶

Updated template and bumped dependencies

1.1.9 (19-12-2019)¶

Added feature for aws application

1.1.10 (13-01-2020)¶

Added api exhaustion backoff.

1.1.11 (13-01-2020)¶

Corrected Pipfile.lock issue.

1.1.12 (09-06-2020)¶

Bumped requests

1.1.13 (17-06-2020)¶

fixed applications entity

1.2.0 (09-10-2020)¶

bumped requests

1.3.0 (02-12-2020)¶

Bumped requests

1.4.0 (15-03-2021)¶

Added property setters for user attributes.

1.4.1 (26-04-2021)¶

Bumped dependencies.

1.4.2 (08-06-2021)¶

Bumped dependencies.

1.4.3 (08-06-2021)¶

Updated reference of pypi to simple from legacy.

1.4.4 (08-06-2021)¶

Updated pypi reference.

1.4.5 (08-06-2021)¶

Reverted pypi reference to legacy.

1.5.0 (24-03-2022)¶

Added User and Group assignment roles.

1.6.0 (28-03-2022)¶

Made entities comparable.

1.6.1 (22-04-2022)¶

Fixed bugs with api rate limiting courtesy of Yorick Hoorneman <yhoorneman@schubergphilis.com>

2.0.0 (30-01-2023)¶

Fixed a nasty bug with activate and deactivate of applications being exposed as properties with bad side effects on introspection. Made most entities return as generators.

2.0.1 (28-02-2023)¶

Testing release.

2.0.2 (07-03-2023)¶

Test release.

Welcome to oktalib’s documentation!¶

oktalib¶

Development Workflow¶

Important Information¶

Project Features¶

Todo¶

Installation¶

Usage¶

Contributing¶

Submit Feedback¶

Get Started!¶

oktalib¶

oktalib package¶

Subpackages¶

oktalib.entities package¶

Submodules¶

oktalib.entities.core module¶

oktalib.entities.entities module¶

Module contents¶

Submodules¶

oktalib.oktalib module¶

oktalib.oktalibexceptions module¶

Module contents¶

Credits¶

Development Lead¶

Contributors¶

History¶

0.1.0 (25-05-2018)¶

1.0.0 (19-10-2018)¶

1.1.0 (23-10-2018)¶

1.1.1 (25-10-2018)¶

1.1.2 (17-12-2018)¶

1.1.3 (11-01-2019)¶

1.1.4 (20-09-2019)¶

1.1.5 (20-09-2019)¶

1.1.6 (23-09-2019)¶

1.1.7 (18-10-2019)¶

1.1.8 (18-10-2019)¶

1.1.9 (19-12-2019)¶

1.1.10 (13-01-2020)¶

1.1.11 (13-01-2020)¶

1.1.12 (09-06-2020)¶

1.1.13 (17-06-2020)¶

1.2.0 (09-10-2020)¶

1.3.0 (02-12-2020)¶

1.4.0 (15-03-2021)¶

1.4.1 (26-04-2021)¶

1.4.2 (08-06-2021)¶

1.4.3 (08-06-2021)¶

1.4.4 (08-06-2021)¶

1.4.5 (08-06-2021)¶

1.5.0 (24-03-2022)¶

1.6.0 (28-03-2022)¶

1.6.1 (22-04-2022)¶

2.0.0 (30-01-2023)¶

2.0.1 (28-02-2023)¶

2.0.2 (07-03-2023)¶

Indices and tables¶