shopify / oktakit

Ruby toolkit for working with the Okta API

oktakit

Ruby toolkit for the Okta API.

Installation

Add this line to your application's Gemfile:

gem 'oktakit'

And then execute:

bundle

Usage

Oktakit follows similar patterns as found in Octokit. So if you are familiar with Octokit, then you should feel right at home.

client = Oktakit.new(token: 't0k3n', organization: 'my-great-org')
response, http_status = client.list_users

To work with the Okta sandbox (<organization>.oktapreview.com), set the api_endpoint:

client = Oktakit.new(token: 't0k3n', api_endpoint: 'https://my-great-org.oktapreview.com/api/v1')

Pagination

Pass the paginate flag as options for any get action for Oktakit to autopaginate the response for you.

client = Oktakit.new(token: 't0k3n', organization: 'my-great-org')
response, http_status = client.list_users(paginate: true)

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release to create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Testing

Testing is fairly straightforward, with the exception of the org URL. To anonymize the VCR data, first setup a real token and endpoint for Okta, such as myokta.okta.com

• In spec_helper.rb, set the org to my-okta (or whatever your organization is).
• Set the OKTA_TEST_TOKEN environment variable (this should be real). Don't worry, it is automatically removed.
• Before committing, change my-okta to okta-test in spec_helper.rb and any VCR Cassettes.

The API Test Client provided by Okta is also really helpful.

Contributing

1. Fork it ( https://github.com/shopify/oktakit/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributor License Agreement

New contributors will be required to sign Shopify's Contributor License Agreement (CLA). There are two versions of the CLA: one for individuals and one for organizations.

oktakit's Issues

Support for System Log

Could you add support for https://developer.okta.com/docs/api/resources/system_log.html ?

Thanks!

Event Hook API support

Would you accept Event Hook API support if I contribute it?

Migrate to GitHub Actions to speed up CI

Today it takes many hours for travis to queue jobs, let's try out https://github.com/features/actions to see if it's a better experience

Genghis flow for staging2

Currently, the genghis flow only operates on our staging environment, it should also be able to point at staging2.

This could be accomplished by either adding new flows that point to staging2 or adding calls in the existing verify flow to also make calls to staging2. If that method is chosen however, every genghis run will hit both environments so likely do the first option.

Rate Limit

Observation

Various solutions pull data from Okta and due the increase api calls to this service we are hitting rate limits.
However Okta provides information in its header to help determine when we are approaching the limit.

Ref: https://developer.okta.com/docs/reference/rl-best-practices/

Example of Rate Limit header with org-wide rate limit

HTTP/1.1 200
Date: Tue, 27 Jan 2018 21:33:25 GMT
X-Rate-Limit-Limit: 600
X-Rate-Limit-Remaining: 598
X-Rate-Limit-Reset: 1516308901

Solution

Add logic to back off for x time when X-Rate-Limit-Remaining value is less than x ( I am thinking about 10 )
We can also pair with the X-Rate-Limit-Reset value to determine the reset period as well.

Create a CONTRIBUTING.md

https://github.com/Shopify/krane/blob/master/CONTRIBUTING.md looks like a thorough example 😄

[Question] Considering making a PR for exposing pagination

Hi there! First off, really appreciate this project. It's shaved days off my timelines.

I'm considering doing a PR against this project for exposing pagination in an easier way. I extended the oktakit client quick and dirty like this for my project, and thought it might be a nice method for this gem (I skimmed open PRs and issues and didn't see anything already in the pipes).

I'd want to clean this up more, but wanted to ask here first to see if some better approach already exists, or if you think this would help:

class OktaClient < Oktakit::Client

 # This is copied from https://github.com/Shopify/oktakit/blob/master/lib/oktakit/client.rb#L65, but this just fetches a single page, instead of recursing to fetch every page
  def alt_get(url, options = {})
    should_paginate = options.delete(:paginate)
    request_options = {
      query: options.delete(:query),
      headers: options.delete(:headers),
      accept: options.delete(:accept),
      content_type: options.delete(:content_type),
      paginate: should_paginate,
      data: options
    }

    resp, status, next_page = request(:get, url, **request_options)

    [resp, status, next_page]
  end

  def get_each_page(url, options = {})
    next_page = url
    while next_page
      resp, status, next_page = alt_get(next_page, options.merge(paginate: true))
      raise RequestError, "Error fetching okta #{url}, status=#{status}, response=#{resp}" unless status == 200

      yield(resp, status, next_page)
    end
  end

end

I'm just trying to help though! I'm happy to just keep my extension, so feel free to ignore and close with or without comment :)

oktakit: Classification Check

Classification Check

TL;DR

1st party software must have a business impact classification. See our list of classification to help you determine the classification of your application.

Why is this being asked?

It's critical that we understand the business impact of the software we write. The classification of your service determines the level of support you must provide as owners and helps us set standards.

What will happen if it doesn't get done within the expected timeframe?

This is mandatory. If this is not done you won't be able to have any runtimes.

When does it need to get done?

At the latest, this should be done before 2021-07-22.

This doesn't apply to my service. What do I do?

First, leave a comment explaining why it doesn't apply. Then, leave another comment as /not_applicable, and close the issue.
If you change your mind, make sure to comment any reason and reopen the issue.

I have questions/concerns about this

Please contact the Production Excellence team using Slack at #production-excellence-team.
Your service: oktakit/production
Owners:

Unable to test out of the box

The tests no longer pass out of the box following instructions in https://github.com/Shopify/oktakit#testing.

Following the instructions cause a number of requests to fail due to changes in Okta or with HTTP 404 as constants are no longer valid. For example #create_user in user_spec.rb fails as the password cannot contain a significant portion of the question now. When changes are made to get those tests to pass, others with ID constants like USERS_USER_ID fail as the resource is not found.

Without making changes to spec_helper.rb all of the tests pass except the errors tests. It appears that Oktakit::Response::RaiseError is no longer used by Faraday or through some combination with VCR.

Add support for Okta's new Identity Engine

👋 Okta is in the process of releasing a new Identity Engine which changes the way authentication to the API is handled. Opening this issue to track this in case it isn't on your radar already.

Resources:

• OIE Upgrade Overview
• okta-authn-js Migration Doc

Paginated API URL's should be excluded from being escaped

When I query an paginated endpoint with a date-filter, next-refs are double escaped.

If you start with a paginated request like this.

client.get('/logs?since=2019-08-01T00:00:00.000Z&until=2019-08-15T00:00:00.000Z&filter=eventType+eq+"user.session.start"', paginate: true)

The raw response of the HTTP-request will contain a link to the next page:

/logs?after=1565220135395_1&filter=eventType+eq+%22user.session.start%22&since=2019-08-01T00%3A00%3A00.000Z&until=2019-08-15T00%3A00%3A00.000Z

But request (found here) will also URI-escape the already escaped URL, resulting in double escaped URI's and hence in a Oktakit::BadRequest

/logs?after=1565220135395_1&filter=eventType+eq+%2522user.session.start%2522&since=2019-08-01T00%253A00%253A00.000Z&until=2019-08-15T00%253A00%253A00.000Z

Oktakit::BadRequest: 400 - The date format in your query is not recognized. Please enter dates using the Internet Date/Time Format profile of ISO 8601.

Make New Release

We are due to package a new release of oktakit.

`raise Oktakit::Error.from_response(response)` fails with `TypeError`

Hi there,

I've encountered an unexpected behavior when trying to raise Oktakit::Error.from_response(response) causing TypeError - exception object expected with oktakit version 0.3.1.

Steps to reproduce

okta_client = Oktakit.new(token: token, api_endpoint: api_endpoint)
response, http_status = okta_client.get_user('[email protected]')

# response
#-> {:errorCode=>"E0000007", :errorSummary=> "Not found: Resource not found: [email protected] (User)", :errorLink=>"E0000007", :errorId=>"oaeLRic8zbhTBiJ81eJnWTQUg", :errorCauses=>[]}
# response.class
#-> Sawyer::Resource

raise Oktakit::Error.from_response(response) unless http_status == 200
#->TypeError - exception object expected:
#-> ... trace ...

###
response = {:errorCode=>"E0000007", :errorSummary=> "Not found: Resource not found: [email protected] (User)", :errorLink=>"E0000007", :errorId=>"oaeLRic8zbhTBiJ81eJnWTQUg", :errorCauses=>[]}
###

# lib/oktakit/error.rb
module Oktakit
  # Custom error class for rescuing from all Okta errors
  class Error < StandardError
    # Returns the appropriate Oktakit::Error subclass based
    # on status and response message
    #
    # @param [Hash] response HTTP response
    # @return [Oktakit::Error]
    def self.from_response(response)
      status = response[:status].to_i # nil.to_i = 0
      if (klass = error(status)) # this block returns nil
        klass.new(response)
      end
    end
    ...
    
    def build_error_message
      return nil if @response.nil?

      message =  "#{@response[:method].to_s.upcase} " # no corresponding attribute
      message << redact_url(@response[:url].to_s) + ': ' # same here
      message << "#{@response[:status]} - " # and same here
      message << response_message.to_s unless response_message.nil?
      message
    end
    ...

It looks like the structure of the response object for errors has changed (documentation link).

Auth implementation

Is there was to easily implement these apis?

https://developer.okta.com/docs/reference/api/authn/

update_user is hardcoded to PUT

oktakit/lib/oktakit/client/users.rb

Lines 62 to 64 in 3ffb4ef

	def update_user(id, options = {})
	put("/users/#{id}", options)
	end

whereas POST is needed for any partial update.
https://developer.okta.com/docs/api/resources/users#update-user

Not sure how you want to handle multiple verbs per method. Am not experienced in idiomatic ruby. Would be happy to write the PR given an opinion of how that is normally done.

Not compatible with modern Faraday

Problem

The current version of Faraday doesn't appear to be compatible with the latest release of Oktakit (2017), and it's beginning to block other gem upgrades.

Details

The issues I'm aware of are both around the RaiseError middleware:

• #38 addresses the calling style for that middleware
• builder.use apparently isn't appropriate for this type of middleware anymore (they want you to use builder.adapter I think?

(My attempts to monkey-patch the latter have all failed though, so I could be misunderstanding the problem).

Add Reactivate-Delete

Hi there, first thanks for this great gem, it really saved me a lot of time. With that said as we advanced in our integration with the Okta API using this gem we realized that there were some functionalities that we needed and wasn't there, like reactivate an user (resend the welcome email to a user) and delete an user. So I forked the repository, and added such functionalities with some tests too.I Hope you find it useful.