Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Working with Bundler
      • Rails Support
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with Spring Boot
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Data For Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
    • Single Sign-on (SSO)
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Extending Heroku
  • Building Add-ons
  • How Add-ons Work

How Add-ons Work

English — 日本語に切り替える

Last updated July 13, 2020

Table of Contents

  • Provisioning
  • Consumption
  • Updating config vars and add-on security
  • Single sign on

Heroku customers use the marketplace or the Heroku CLI to provision your add-on. When this happens, Heroku sends a request to your service, which creates a new private resource for the app.

This resource represents your service, and is what the client application will interact with.

The URI representing the resource is made available to the app as a config var. The app can then consume its private resource via a library, plugin, or over HTTP, depending on your service.

Add-on Overview

Provisioning

Customer adds add-on

Provision Step 1

The provisioning process begins when a Heroku customer finds your add-on in the add-ons catalog and clicks Add, or alternatively, they can use the command line tool:

$ heroku addons:create addon-name

Heroku requests service provisioning

Provision Step 2

The make-up of the provisioned resource(s) depends on the type of service you’re operating.

In almost every case, you will want to provision a user account. However, a database add-on partner may choose to also immediately create a database that the app can start using, whereas exception reporting service may issue an API key in addition to the user credentials.

Return resource URL

Provision Step 3

Once the resource is created, your service will respond with a URL with the exact location and credentials that the app can use to access their private resource.

For example, a database partner like Amazon RDS may return:

MYSQL_URL=mysql://user:pass@mysqlhost.net/database

A general partner such as New Relic may return:

NEW_RELIC_URL=http://newrelic.com/accounts/[apitoken]

Heroku rebuilds app

Provision Step 4

Heroku adds the returned URL as a config var in the app, rebuilds the slug and restarts all dynos. The user’s app is now ready to consume the resource your cloud service has provisioned for them.

Consumption

Consume Step 1

The app may wish to consume the resource when an end user makes a request to the app from their web browser. Or, a worker dyno in the app may need to consume the resource as part of performing a background job.

For example, a page might wish to consume a database resource by sending a query like “SELECT * FROM table”, or consume a web service with a call like POST /exceptions.

App accesses resource URL

Consume Step 2

The app uses a URL, which was stored as a config var in the app during provisioning, to access the remote resource.

Datastore resources such as MySQL, MongoDB, or Memcache have their own protocol and will use a client library such as ActiveRecord, MongoMapper, or MemcacheClient to access the resource. These resources will have URLs that start with protocol names like mysql://, mongo://, or memcache://.

Web service resources such as Exceptional or New Relic use HTTP as their protocol, so their URLs will begin with https://.

Resource responds

Consume Step 3

The invoked resource within your cloud service can now process the request, assuming the credentials are valid

If it’s a read request (such as SQL’s SELECT or HTTP’s GET) it will look up the information to return to the app. If it’s a write request (such as SQL’s INSERT or HTTP’s POST) it will store that information to the resource and return an acknowledgment.

Once the app has its response, it can use this to build a page for the end user (if this consume request came from a dyno processing a web request), or to continue processing its background job (if this consume request came from a worker).

Updating config vars and add-on security

An add-on partner can update the provided credentials in a config var at any time through the add-ons integration. This happens, for example, when a credentials roll is needed or they change URLs on their end. Because of this, it is recommended that you do not overwrite config vars provided by an add-on

Add-ons can only read the config vars they set on an app, and they can set zero, one, or many config vars. They cannot read config vars you manually set on your app nor those that other add-ons set.

Single sign on

Heroku Dashboard

SSO Step 1

By providing us with your manifest, you will have described your add-on to our system in such a way that we can integrate it into our Marketplace as well as the Dashboard. The Dashboard is where customers manage the resources associated with their app.

A Heroku customer can log into the Heroku Dashboard to view information about their app.

Add-on selection

SSO Step 2

Clicking an app will take you to an in-depth page about on the app, which also shows all the installed add-ons. The customer finds your add-on in the list and clicks on it.

Redirect to add-on property

Heroku generates a single sign-on token using the ID of the resource, the current time, and the salt (a shared secret known to both Heroku and your service).

This generates a request for the user looking something like this:

POST https://yourcloudservice.net/sso/login
id=123&token=4af1e20905361a570&timestamp=1267592469&user@example.com

The add-on partner’s site receives this request, confirms that the token matches, and confirms that the timestamp is fresh. The site can set a cookie in the user’s browser to indicate that they are authenticated, and then redirect to the admin panel for the resource.

Logging users in via SSO

You can log users into your site quickly with SSO URLs. The link can be placed in email or Campfire notifications, and when the user clicks them they can proceed directly to your add-on dashboard.

SSO URLs follow this format:

https://api.heroku.com/myapps/<heroku_id>/addons/<addon_name>

Here is an example:

https://api.heroku.com/myapps/app123@heroku.com/addons/cloudcounter

Additional information can be supplied as GET parameters. The additional keys and values will then be submitted along with the rest of the user data via SSO POST and allow you to set relevant state or context for the user within your dashboard, e.g.:

https://api.heroku.com/myapps/app123@heroku.com/addons/cloudcounter?issue_no=42

Keep reading

  • Building Add-ons

Feedback

Log in to submit feedback.

What Is an Add-on? [Legacy] Building an Add-on

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

Your email address:

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Heroku Podcasts
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
  • YouTube
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies
  • Cookie Preferences