MIP User Guide for Grand Lodge Offices

Beta. MIP is on and in testing for Grand Lodges. For the short overview, see Member Interchange Protocol (MIP).

What is MIP?

The Member Interchange Protocol (MIP) connects your Grand Lodge with other membership organizations that use it. Once you're connected, you can:

• Look up a member in a connected organization's records
• See that member's current status there
• Request and receive Certificates of Good Standing electronically
• Find other organizations on the MIP network

MIP works directly between your system and the other organization's system. Groupable runs your side and acts as your data processor for the exchange, with Amazon Web Services (AWS) as its sub-processor for hosting. No organization outside the two in a request ever sees your members' information. Each organization decides who it connects with, what it shares, and how it answers requests. Each connection's Data Processing Chain (see Connection Details below) shows the chain both sides have declared.

Getting Started

Setting Up MIP

MIP is set up once for your Grand Lodge. Setting it up takes the Group Admin role. The person who sets it up also needs the My group advanced write permission, which the Group Read Write role includes. Group Admin doesn't include it. With Group Admin alone, Save stores your details and then shows a permissions message, and My Config won't open.

1. From the main menu, click Related Groups.
2. At the top of the page, next to Connect with Other Organizations, click Set Up MIP. Without the Group Admin role, you see a note to contact your group administrator instead of the button.
3. Fill in the form and click Save.

Every field is required except the on-behalf-of box and the check boxes.

The form's seven check boxes are explained under Configuration Options below.

When you save, MIP creates your organization's MIP ID and the security keys that protect every message you exchange. You don't need to do anything with the keys.

From then on, Related Groups in the main menu opens Related Groups Communications, your MIP home page.

Your MIP Identity

Click My Config to open the MIP Configuration page. It shows your organization's identity:

Related Groups Communications (your MIP home page)

All MIP work starts on Related Groups Communications. The Action Items card on your Grand Lodge's home page in M2 also counts pending MIP searches, certificate requests, and connections, and links here. MIP doesn't send email about new requests, so check one or the other.

Across the top are five counts: Connected Groups, Pending connections, Pending Searches, Pending COGS (certificates of good standing), and Unresolved Connections.

Below the counts are up to five buttons. New Search, Request Certificate, Request Connection, and My Config appear if you have the My group advanced write permission. Provenance Report appears if you have the Group Admin role. It lists your connections with their data protection role and platform, and counts the searches and certificates that carried member data.

If you have My group advanced write, three lists sort your MIP work.

Action Required holds anything waiting on you. Each item has a button for its next step:

Waiting on Others holds requests you sent that haven't been answered. After 30 days with no answer, an item moves to Action Required so you can close it.

Done holds finished items: answers you sent that were delivered, connections linked to a related group, and anything you marked done. Items stay there for 60 days, then move to the archive. The archive icon at the top of Done opens it.

Below the lists, the MIP Groups table lists every organization your Grand Lodge knows through MIP, with its MIP Status, endorsements, Trusted Authenticator setting, and authentication type. Organizations marked UNCONNECTED were introduced by one of your connections. The Unconnected Groups table lists your own related groups that don't have an MIP connection yet. View Full Directory opens your full Related Groups list.

Managing Connections

You need an active connection before you can exchange anything with another organization. Requesting, approving, and declining connections take the My group advanced write permission, in a group-level role.

Requesting a Connection

1. On Related Groups Communications, click Request Connection.
2. In Foreign Organization URL, enter the other organization's MIP web address. A Groupable organization finds its own on My Config, under My MIP Web Address.
3. Choose the Related group it matches in your system. If it isn't one of your related groups, check This connection is not with one of our related groups instead and enter a Reason. You must do one or the other.
4. Leave Share My Organization checked to let the other organization tell its connections about you. This helps others find you. It doesn't share any member data.
5. The Trusted Authenticator box asks whether you trust this organization to vouch for others. When the other organization approves, MIP currently marks the connection a Trusted Authenticator whatever you chose here. See Trusted Authenticators below to turn that off.
6. Click Create Connection.

If you start from the Invite button next to a group on your Related Groups list, that group is already chosen as the Related group.

Your request waits under Waiting on Others until the other organization approves or declines it.

Approving an Incoming Connection

A request to connect appears under Action Required.

1. Click Review to open the connection.
2. Check the organization's name, contact person, and Public Key Fingerprint.
3. To make sure the request is real, call the contact person and confirm the fingerprint matches what they see on their own My Config page.
4. Under Approve, choose the Related group this connection belongs to. If it isn't one of your related groups, check This connection is not with one of our related groups instead and enter a Reason. You can't approve until you do one or the other.
5. Click Approve. To turn the request down instead, click Decline.

Once approved, both organizations can start exchanging member information. Approving also makes the connection a Trusted Authenticator (see Web of Trust).

Connection Details

In the MIP Groups table, click a connection's name. If the connection is linked to one of your related groups, that group's page opens. While the connection is active, click View Details there. If it isn't linked, the connection's page opens directly. Either way, you need the My group advanced write permission. Without it, View Details doesn't appear.

The connection's page shows:

• Type (Incoming or Outgoing), related group, and status
• Authentication type (MANUAL or ENDORSEMENT, or Not Yet Authenticated before approval)
• Organization name, contact person, phone, and website
• MIP ID, MIP Web Address, and Public Key Fingerprint
• Whether it's a Trusted Authenticator, and whether you've endorsed it (with the date your endorsement expires)
• Third-Party Endorsements: other organizations that have vouched for it
• Data Processing Chain: who is the data controller and processor on each side
• The other organization's GDPR / Compliance Contact

While the connection is active, you can click Enable Trusted Authenticator or Disable Trusted Authenticator on this page, and the link icon at the top of the card (Resolve Connection) changes which related group the connection belongs to. On an active connection another organization asked you for, Resend approval sends your approval to them again.

Discovering New Organizations

When you connect with an organization, it may share other organizations it knows. These appear in the MIP Groups table as UNCONNECTED. To connect with one, click the Request Connection icon in its row. The request form opens with its web address filled in.

If you turn on Automatically attempt connections for unconnected organizations from trusted shared MIP nodes in your configuration, MIP sends a connection request for you whenever a Trusted Authenticator shares an organization you aren't connected to yet. The request then waits for the other organization, like any request you send.

Searching for Members

A member search looks up a person in a connected organization's records. Sending searches and answering incoming ones take the My group advanced write permission, in a group-level role.

Sending a Search Request

1. On Related Groups Communications, click New Search.
2. Choose the Connection to search.
3. Enter the Member Number at the other organization. This field is required. Also enter First Name and Last Name. Without them, the other organization's results can include its whole membership, not only the person you're looking for. Add Birthdate to narrow the results further.
4. Click Search.

Your search waits under Waiting on Others until the other organization answers.

Receiving Search Results

When the answer comes back, the search moves to Action Required. Click Review to open it.

The Search Results table shows each matching member's name, member number, status, and the lodges they belong to. To request a Certificate of Good Standing for one of them, click Request Certificate in that member's row. The request form opens with the member's details filled in.

If nobody matches, the page says no matching members were found. If the other organization declined your search, the status shows Declined with their reason.

The search stays in Action Required until you click Mark done.

Answering Incoming Search Requests

When another organization searches your records, the request appears under Action Required.

1. Click Respond. The page shows what they sent and the members in your records that match: members with that member number, or whose first and last names start with the letters sent. If they sent no names, every member is listed.
2. Each match shows name, member number, status, type, good standing, and whether the birthdate matches. A row whose birthdate doesn't match is highlighted and marked Mismatch.
3. Check the members to send. Check only the person they asked about.
4. Click Approve and Send Selected Members. If no one matches, the button reads Approve with No Matches. If the list shows people but none of them is the person asked about, leave them all unchecked and click Approve and Send Selected Members. That answers with no members.
5. To say no instead, click Decline Request, give a reason of 10 to 500 characters, and click Decline and Notify. The reason is sent to the other organization.

If your answer doesn't get through (for example, the other system is down for a while), MIP keeps retrying on its own. Until it's delivered, the request stays in Action Required with a Resend button. The request's own page has Resend too.

Certificates of Good Standing

A Certificate of Good Standing confirms that a member is in good standing with their organization. It's valid for 90 days from the day it's issued. Requesting certificates and answering requests take the My group advanced write permission, in a group-level role.

Requesting a Certificate

1. On Related Groups Communications, click Request Certificate. In search results, Request Certificate in a member's row opens the same form with the member filled in.
2. Choose the Connection.
3. Enter the Member Number, First Name, and Last Name. Birthdate and Notes are optional.
4. Click Request Certificate.

The request waits under Waiting on Others until the other organization answers.

Viewing a Received Certificate

When the answer comes back, the request moves to Action Required. Click Review to open it.

Check the Valid until date yourself. The page doesn't warn you when a certificate has expired.

If the request was declined, the page shows their reason. The request stays in Action Required until you click Mark done.

Answering Incoming Certificate Requests

When another organization requests a Certificate of Good Standing from you, the request appears under Action Required.

1. Click Respond. The page shows what they sent, any Notes from Requester, and the members in your records that match.
2. Choose the member with the radio button. MIP preselects a match whose birthdate agrees.
3. Check or clear Member is in Good Standing. It starts out set from the preselected member's status. If you choose someone else, set it yourself.
4. Click Approve and Issue Certificate. To say no instead, click Decline Request.
5. If you decline, give a reason of 10 to 500 characters and click Decline and Notify.

If no one matches, the button reads Approve Without Member Match. That still issues a 90-day certificate, and it shows Good Standing as No unless you check Member is in Good Standing. If you have no record of the person, decline and say so in the reason.

As with searches, MIP retries an answer that doesn't get through, and Resend sends it again.

Web of Trust

How It Works

When you approve a connection, the two organizations exchange endorsements. An endorsement is a digital signature one organization gives to vouch for another's identity. Endorsements last one year.

When an organization asks to connect, its request can carry endorsements from organizations you already trust. If one of your Trusted Authenticators has endorsed it, MIP approves the connection automatically, with no one reviewing it. The connection is active right away and becomes a Trusted Authenticator itself. Searches and certificate requests from it still wait for your review. Until you link it to a related group, it shows in Action Required with a Resolve button.

Trust Threshold

One endorsement from a Trusted Authenticator is enough for automatic approval. To change that, contact Groupable support.

Trusted Authenticators

Only endorsements from Trusted Authenticators count toward automatic approval. Every connection you approve becomes one, and so does every connection you request once the other organization approves it.

To take that trust away, open the connection's page and click Disable Trusted Authenticator, or turn off the switch in the Trusted Authenticator column of the MIP Groups table. Enable Trusted Authenticator turns it back on.

Viewing Endorsements

My Config lists the endorsements your organization has received: who endorsed you, whether each one is Valid, Expired, or Revoked, and when it expires. A connection's page lists the endorsements other organizations have given it, under Third-Party Endorsements.

Configuration Options

My Config shows your settings. To change them, click the edit (pencil) icon. Editing takes the Group Admin role, and opening My Config takes My group advanced write, so you need both.

Two of the seven options change how MIP works today. The other five are saved with your configuration but have no effect yet. The table says which.

Permissions

For connections, searches, and certificates, you must be working in a group-level role, not a local one. Group Admin is a role. The other two are permissions inside a role, and the standard Group Read Write role includes both.

Security

• All MIP traffic travels over HTTPS, so it's encrypted in transit.
• Every request is signed with the sending organization's private key. The receiving system checks the signature to confirm the request is real and hasn't been changed.
• Every request carries a timestamp. Requests more than a minute old, and repeats of recent requests, are rejected.
• Each connection is limited to 100 requests a day by default.
• Your organization's private key is stored encrypted in the database.
• MIP only connects to public web addresses. It refuses private and reserved network addresses.
• Member data travels directly between the two organizations in a request. No other organization relays or handles it. Groupable, as your data processor, and AWS, as its sub-processor, host your side. See Data Processing Chain under Connection Details.

Glossary