class Nylas::Auth

Auth

Public Instance Methods

access_token_info(query_params: nil) click to toggle source

Get info about a specific token based on the identifier you include. Use either the ID Token or Access Token.

@param ID of the request. @return [Hash] Token Info.

# File lib/nylas/resources/auth.rb, line 24
def access_token_info(query_params: nil)
  get(
    path: "#{api_uri}/v3/connect/tokeninfo",
    query_params: query_params
  )
end
custom_authentication(request_body) click to toggle source

Create a Grant via Custom Authentication.

@param request_body [Hash] The values to create the Grant with. @return [Array(Hash, String)] Created grant and API Request ID.

# File lib/nylas/resources/auth.rb, line 53
def custom_authentication(request_body)
  post(
    path: "#{api_uri}/v3/connect/custom",
    request_body: request_body
  )
end
detect_provider(params) click to toggle source

Detects the provider of an email address. @param params [Hash] Parameters to detect the provider. @return [Array(Hash, String)] Detected provider, if found and API Request ID.

# File lib/nylas/resources/auth.rb, line 118
def detect_provider(params)
  post(
    path: "#{api_uri}/v3/providers/detect",
    query_params: params
  )
end
exchange_code_for_token(request) click to toggle source

Exchanges an authorization code for an access token.

@param request [Hash] Code exchange request. @return [Hash] Token object.

# File lib/nylas/resources/auth.rb, line 43
def exchange_code_for_token(request)
  request[:grant_type] = "authorization_code"

  execute_token_request(request)
end
refresh_access_token(request) click to toggle source

Refreshes an access token.

@param request [Hash] Code exchange request. @return [Hash] Refreshed token object.

# File lib/nylas/resources/auth.rb, line 64
def refresh_access_token(request)
  request[:grant_type] = "refresh_token"

  execute_token_request(request)
end
revoke(token) click to toggle source

Revokes a single access token.

@param token [String] Access token to revoke. @return [Boolean] True if the access token was revoked successfully.

# File lib/nylas/resources/auth.rb, line 105
def revoke(token)
  post(
    path: "#{api_uri}/v3/connect/revoke",
    query_params: {
      token: token
    }
  )
  true
end
url_for_oauth2(config) click to toggle source

Builds the URL for authenticating users to your application with OAuth 2.0.

@param config [Hash] Configuration for building the URL. @return [String] URL for hosted authentication.

# File lib/nylas/resources/auth.rb, line 35
def url_for_oauth2(config)
  url_auth_builder(config).to_s
end
url_for_oauth2_pkce(config) click to toggle source

Builds the URL for authenticating users to your application with OAuth 2.0 and PKCE.

IMPORTANT: You must store the 'secret' returned to use it inside the CodeExchange flow.

@param config [Hash] Configuration for building the URL. @return [Hash] URL for hosted authentication with the secret and the hashed secret.

# File lib/nylas/resources/auth.rb, line 75
def url_for_oauth2_pkce(config)
  url = url_auth_builder(config)

  # Generates a secret and hashes it.
  secret = SecureRandom.uuid
  secret_hash = hash_pkce_secret(secret)

  # Adds code challenge to URL generation.
  url.query = build_query_with_pkce(config, secret_hash)

  # Returns the URL with secret and hashed secret.
  { secret: secret, secret_hash: secret_hash, url: url.to_s }
end

Private Instance Methods

build_http_query(config) click to toggle source

Builds the query.

@param config [Hash] Configuration for the query. @return [Hash] List of parameters to encode in the query.

# File lib/nylas/resources/auth.rb, line 175
def build_http_query(config)
  params = {
    client_id: config[:client_id],
    redirect_uri: config[:redirect_uri],
    access_type: config[:access_type] || "online",
    response_type: "code"
  }
  params[:provider] = config[:provider] if config[:provider]
  params[:prompt] = config[:prompt] if config[:prompt]
  params[:metadata] = config[:metadata] if config[:metadata]
  params[:state] = config[:state] if config[:state]
  params[:scope] = config[:scope].join(" ") if config[:scope]
  if config[:login_hint]
    params[:login_hint] = config[:login_hint]
    params[:include_grant_scopes] = config[:include_grant_scopes].to_s if config[:include_grant_scopes]
  end

  params
end
build_query_with_pkce(config, secret_hash) click to toggle source

Builds the query with PKCE.

@param config [Hash] Configuration for the query. @param secret_hash [Hash] Hashed secret. @return [String] Updated list of encoded parameters, including those specific to PKCE.

# File lib/nylas/resources/auth.rb, line 149
def build_query_with_pkce(config, secret_hash)
  params = build_http_query(config)

  # Appends new PKCE specific params.
  params[:code_challenge_method] = "s256"
  params[:code_challenge] = secret_hash

  URI.encode_www_form(params).gsub("+", "%20")
end
execute_token_request(request) click to toggle source

Sends the token request to the Nylas API.

@param request [Hash] Code exchange request.

# File lib/nylas/resources/auth.rb, line 207
def execute_token_request(request)
  request[:client_secret] = api_key if request[:client_secret].nil?

  execute(
    method: :post,
    path: "#{api_uri}/v3/connect/token",
    query: {},
    payload: request,
    headers: {},
    api_key: api_key,
    timeout: timeout
  )
end
hash_pkce_secret(secret) click to toggle source

Hash a plain text secret for use in PKCE.

@param secret [String] The plain text secret to hash. @return [String] The hashed secret with base64 encoding (without padding).

# File lib/nylas/resources/auth.rb, line 199
def hash_pkce_secret(secret)
  sha256_hash = Digest::SHA256.hexdigest(secret)
  Base64.urlsafe_encode64(sha256_hash, padding: false)
end
url_auth_builder(config) click to toggle source

Builds the authentication URL.

@param config [Hash] Configuration for the query. @return [URI] List of components for the authentication URL.

# File lib/nylas/resources/auth.rb, line 163
def url_auth_builder(config)
  builder = URI.parse(api_uri)
  builder.path = "/v3/connect/auth"
  builder.query = URI.encode_www_form(build_http_query(config)).gsub(/\+/, "%20")

  builder
end